CMS Configuration
Learn how to integrate a CMS integration with the Alokai Storefront
Content Management System
In today's digital landscape, the content drives user engagement. As eCommerce platforms strive to deliver personalized user experiences, integrating a robust Content Management System (CMS) becomes crucial.
Significance of Content in Digital eCcommerce:
- Engagement: Quality content captivates users, enhancing their experience and loyalty.
- SEO: Optimized content improves search rankings, driving organic traffic.
- Trust: Authentic content builds trust, encouraging purchases.
- Branding: Content conveys a brand's values and identity, differentiating it from competitors.
In essence, quality content is pivotal for user engagement in eCommerce, and a robust CMS ensures efficient content delivery and management.
Available Integrations
Currently, Alokai Storefront supports these CMS integrations:
It's important to note that the Unified Data Layer only supports e-commerce platforms. This means that CMS integrations are not part of the Unified Data Layer, but they can be integrated individually with your storefront.
How to Start?
All of the CMS integrations contain two main parts:
- An API Client that extends the middleware to interact with your CMS service.
- An SDK Module that extends the SDK to provide type-safe methods to interact with the Middleware.
In this guide, we'll focus on the Contentful integration. However, the process is similar for other CMS integrations. You can find specific installation guides for each integration in their documentation.
Installing the API Client (Middleware)
The first step is to configure the Contentful API Client. The API Client serves as the bridge between your application and external services, ensuring secure and efficient data transmission.
Want to read more about our architecture? Please check this architecture guide.
To configure it:
- Jump into the configuration in
apps/storefront-middleware
app. - Install Contentful dependencies.
yarn add @vsf-enterprise/contentful-api
- Create a dedicated directory in the
integrations
directory with the name of the CMS integration. In our case it will be:contentful
. - Then create a
config.ts
file and input the required details.
Keep in mind, different CMS platforms have their own unique secrets and environment variables. If you're unsure about what to input, it's recommended to refer to the module's documentation. Typically, these documents provide general examples that can guide you in populating the right information.
// integrations/<integration>/config.ts
import type { MiddlewareConfig } from "@vsf-enterprise/contentful-api";
import type { Integration } from "@vue-storefront/middleware";
const { CNTF_TOKEN, CNTF_SPACE, CNTF_ENVIRONMENT } = process.env;
if (!CNTF_TOKEN) throw new Error("Missing env var: CNTF_TOKEN");
if (!CNTF_SPACE) throw new Error("Missing env var: CNTF_SPACE");
if (!CNTF_ENVIRONMENT) throw new Error("Missing env var: CNTF_ENVIRONMENT");
export const contentfulConfig = {
location: "@vsf-enterprise/contentful-api/server",
configuration: {
token: CNTF_TOKEN,
space: CNTF_SPACE,
environment: CNTF_ENVIRONMENT,
},
} satisfies Integration<MiddlewareConfig>;
From our setup, you'll notice that we've utilized environmental variables. For enhanced security in your connections, we strongly advise following a similar approach. To do so just add these to your .env
file.
# contentful delivery token
CNTF_TOKEN=
# contentful space
CNTF_SPACE=
# contentful branch
CNTF_ENVIRONMENT=
Please remember that other CMS platforms, such as Contentstack, may require a unique setup when incorporating the API Client. This is because different platforms often have distinct architectures, features, and security protocols. Adhering to each platform's specific requirements ensures optimal integration, performance, and security. To check detailed configuration please refer to the integration documentation.
- Next, create an
index.ts
file in the same directory asconfig.ts
with such an content:
// integrations/<integration>/index.ts
export * from "./config";
- Finally, use this configuration in the
middleware.config.ts
file. Import the CMS integration file, and add the config into theintegrations
object.
import dotenv from "dotenv";
dotenv.config();
import { sapccConfig } from "./integrations/sapcc";
import { contentfulConfig } from "./integrations/contentful";
export const config = {
integrations: {
cntf: contentfulConfig,
commerce: sapccConfig,
},
};
Adding the SDK Module
Now, in our frontend application, we can add our Contentful SDK Module.
- Install the CMS SDK Module in your storefront application.
yarn workspace storefront-unified-nextjs add @vsf-enterprise/contentful-sdk
# or
yarn workspace storefront-unified-nuxtjs add @vsf-enterprise/contentful-sdk
- Register an SDK Contentful module in a
createSdk
factory function.
/* sdk/index.ts */
import { contentfulModule } from "@vsf-enterprise/contentful-sdk";
export const { getSdk } = createSdk(options, ({ buildModule, config }) => ({
contentful: buildModule(contentfulModule, {
apiUrl: `${config.middlewareUrl}/cntf`,
}),
// other modules
}));
Now, the Contentful SDK methods will be available in sdk.contentful.{methodName}
. This will allow you to interact with the Contentful API from your storefront.
With the introduction of the new module, integrating and transitioning between different CMS platforms will be notably straightforward. You'll be just switching between the different configuration (variables) and module names. That's it.
Next Steps
To help you get started with CMS integrations, our CLI tool will help you inject pre-configured UI Component and content models for your application. This can help accelerate development by providing a starting point for your CMS integration.
Adding New Components
To use the CLI:
- Open
apps/storefront-unified-nextjs
orapps/storefront-unified-nuxtjs
directory in your terminal - Run the following command.
npx @vsf-enterprise/cms-cli [cms-name] [platform]
[cms-name]
- i.e.contentful
[platform]
- i.e.nuxt
This will create (or overwrite) the following files in your project.
├── components
│ └── cms
│ ├── page
│ │ ├── Accordion.[tsx/vue]
│ │ ├── Banner.[tsx/vue]
│ │ ├── Card.[tsx/vue]
│ │ ├── Editorial.[tsx/vue]
│ │ ├── Gallery.[tsx/vue]
│ │ ├── Grid.[tsx/vue]
│ │ ├── Hero.[tsx/vue]
│ │ ├── NewsletterBox.[tsx/vue]
│ │ ├── ProductCard.[tsx/vue]
│ │ └── Scrollable.[tsx/vue]
│ └── wrappers
│ └── RenderComponent.[tsx/vue]
└── schemas
└── schemas.json
How the Components Work?
We utilize the RenderContent.[tsx/vue]
component to manage, gather, and showcase all components powered by the CMS. This component will be located in the /cms/wrappers
directory. Inside, you'll discover a comprehensive list of components available for use in this Alokai Storefront. Naturally, you have the flexibility to incorporate additional ones as needed.
Creating Components
To learn how to add more components to the Contentful please check the documentation here.
This process will be different for the other CMS systems as it's unique for each integration.
Content Types and Schemas
The primary difference between integrations may be the location of the Content Models and their corresponding Schemas. It's recommended to centralize these schemas in one location.
When tweaking the CMS settings, be it altering available languages or adjusting component structures, it's recommended to first update the [cms]/schema.json
file before incorporating it into the CMS environment.
This approach minimizes discrepancies between your project and reduces the likelihood of manual interventions in the CMS dashboard.
By default, the schema files will be added to the /schemas
folder, we recommending to move them to CMS dedicated folder.
To read more about bootstrapping Components and Content Models within the selected CMS system please refer to the documentations of the certain modules.