Installation

By default, Alokai integration for Contentstack is meant to be used as a Storefront module. However, it can also be installed in any Next or Nuxt application.

Prerequisites

Contentstack access & Stack,
Server Middleware application (latest version),
Install Node.js version 18.x
Next or Nuxt frontend with Alokai SDK installed (latest version)
@vsf-enterprise NPM registry access

Bootstrapping Contentstack

Before you start using our Contentstack integration, you need to bootstrap your Contentstack Stack with Alokai schemas. These schemas are aligned with our out-of-the-box frontend components and are required for the integration to work properly.

The bootstrapping process includes importing integration schemas using Contentstack CLI, setting up Live Preview, and managing content types. For detailed instructions, please refer to our Bootstrapping Contentstack guide.

If you don't have a Contentstack space yet, we suggest you request a demo from the Contentstack team.

Installing dependencies

In your frontend application, install the following dependencies:

yarn

yarn add @vsf-enterprise/contentstack-sdk

In your Server Middleware application, install the following dependencies:

yarn

yarn add @vsf-enterprise/contentstack-api

Adding environment varialbes

In the .env file of your Server Middleware application, add the following envioronment variables:

# required
CNTS_DELIVERY_KEY=<your-contentstack-content-environment>,
CNTS_DELIVERY_TOKEN=<your-contentstack-content-environment>,
CNTS_CONTENT_ENV=<your-contentstack-content-environment>,

# optional
CNTS_CONTENT_BRANCH=<your-contentstack-content-environment>,
CNTS_REGION_KEY=<your-contentstack-content-environment>,
CNTS_PREVIEW_TOKEN=<your-contentstack-content-environment>,
CNTS_PREVIEW_HOST=<your-contentstack-content-environment>,

Information on where to get your Contentstack access token from can be found here.

Configuring Server Middleware

The next step is configuring the Contentstack integration in the Server Middleware.

Key concept - Server Middleware

Middleware concept is described in detail in our Key concepts: Server Middleware docs.

Add the following configuration to your Server Middleware configuration file.

middleware.config.ts

import type { MiddlewareConfig as ContentstackMiddlewareConfig } from "@vsf-enterprise/contentstack-api";
import type { Integration } from "@vue-storefront/middleware";

const { CNTS_DELIVERY_KEY, CNTS_DELIVERY_TOKEN, CNTS_CONTENT_ENV } = process.env;

if (!CNTS_DELIVERY_KEY) throw new Error("Missing env var: CNTS_DELIVERY_KEY");
if (!CNTS_DELIVERY_TOKEN) throw new Error("Missing env var: CNTS_DELIVERY_TOKEN");
if (!CNTS_CONTENT_ENV) throw new Error("Missing env var: CNTS_CONTENT_ENV");

export default {
  integrations: {
    contentstack: {
      location: "@vsf-enterprise/contentstack-api/server",
      configuration: {
        key: CONTENT_DELIVERY_KEY,
        token: CNTS_DELIVERY_TOKEN,
        env: CNTS_CONTENT_ENV,
        branch: CNTS_CONTENT_BRANCH,
        region: CNTS_REGION_KEY ?? "US",
        livePreview: {
          enable: true,
          previewToken: CNTS_PREVIEW_TOKEN,
          host: CNTS_PREVIEW_HOST,
        },
        unified: {
          resolvePages: () => ({
            "/*": {
              type: "page",
            },
          }),
          resolveFallbackPage: () => ({
            type: "page",
          }),
        },
      },
    } satisfies Integration<ContentstackMiddlewareConfig>,
  },
};

Configuring Alokai SDK

The last step in the process is configuring Alokai SDK for Contentstack in your frontend application.

Key concept - SDK

SDK core is described in detail in our SDK docs.

Add the following configuration to your Alokai SDK configuration file:

sdk/modules/contentstack.ts

import { defineSdkModule } from '@vue-storefront/next';
import { contentstackModule } from '@vsf-enterprise/contentstack-sdk';

export const contentstack = defineSdkModule(({ buildModule, config, getRequestHeaders }) =>
  buildModule(contentstackModule, {
    apiUrl: `${config.apiUrl}/contentstack`,
    ssrApiUrl: `${config.ssrApiUrl}/contentstack`,
    defaultRequestConfig: {
      headers: getRequestHeaders(),
    },
  }),
);

sdk/modules/index.ts

export * from './contentstack';
// ... other module exports