Installation

This guide covers integrating Alokai CMS into an existing Alokai storefront (Next.js). The integration consists of three parts: the middleware connector, the SDK module, and the React rendering layer.

Prerequisites

An Alokai storefront (Next.js)
Access to an Alokai CMS instance (see Dev Docs → Local Development)
@alokai/cms-api package available in your registry

Setup

Install the API package
Terminal window
```
yarn add @alokai/cms-api
```

Add the middleware integration

Create apps/storefront-middleware/sf-modules/cms-alokai-cms/config.ts:

import type { ApiClientExtension, Integration } from "@alokai/connect/middleware";
import type { MiddlewareConfig } from "@alokai/cms-api";

const {
  ALOKAI_CMS_BASE_URL = "http://localhost:8787",
  ALOKAI_CMS_EDITION = "main",
  ALOKAI_CMS_SPACE,
  ALOKAI_CMS_TOKEN,
} = process.env;

export const config = {
  configuration: {
    baseUrl: ALOKAI_CMS_BASE_URL,
    edition: ALOKAI_CMS_EDITION,
    space: ALOKAI_CMS_SPACE,
    token: ALOKAI_CMS_TOKEN,
  },
  location: "@alokai/cms-api/server",
} satisfies Integration<MiddlewareConfig>;

Then register it in middleware.config.ts:

import { config as cmsConfig } from './sf-modules/cms-alokai-cms/config';

export default {
  integrations: {
    // ... other integrations
    alokai-cms: cmsConfig,
  },
};

Add the SDK module

Create apps/storefront-unified-nextjs/sdk/modules/unified-alokai-cms.ts:

import { defineSdkModule } from "@vue-storefront/next";
import type { UnifiedAlokaiCmsEndpoints } from "storefront-middleware/types";

export const unifiedAlokaiCms = defineSdkModule(({ buildModule, config, getRequestHeaders, middlewareModule }) =>
  buildModule(middlewareModule<UnifiedAlokaiCmsEndpoints>, {
    apiUrl: `${config.apiUrl}/alokai-cms/unified`,
    ssrApiUrl: `${config.ssrApiUrl}/alokai-cms/unified`,
    defaultRequestConfig: {
      headers: getRequestHeaders(),
    },
  }),
);

import { unifiedAlokaiCms } from "./modules/unified-alokai-cms";

export const sdk = createSdk(options, ({ buildModule }) => ({
  // ... other modules
  unifiedAlokaiCms: buildModule(unifiedAlokaiCms),
}));

Set environment variables

Add to your middleware .env:

ALOKAI_CMS_BASE_URL=https://your-cms.workers.dev
ALOKAI_CMS_SPACE=your-space-id
ALOKAI_CMS_EDITION=main
ALOKAI_CMS_TOKEN=your-api-key

Add the rendering component

Create components/cms/page/render-cms-content.tsx and map your CMS component api_id values to React components:

import type { AgnosticCmsComponent } from "@vsf-enterprise/cms-components-utils";
import Hero from "@/components/cms/page/hero";
import Banner from "@/components/cms/page/banner";
// ... import your other components

const components: Record<string, ComponentType<any>> = {
  Hero,
  Banner,
  // ... register components by their CMS api_id
};

export default function RenderCmsContent({ item }: { item: AgnosticCmsComponent | AgnosticCmsComponent[] }) {
  if (Array.isArray(item)) {
    return (
      <>
        {item.map((c, i) => (
          <RenderCmsContent key={c.id} item={c} />
        ))}
      </>
    );
  }
  const { component, ...props } = item;
  const Component = components[component];
  if (!Component) return null;
  return <Component {...props} />;
}

Fetch and render a page

In a Next.js page or layout:

import { getSdk } from "@/sdk";
import RenderCmsContent from "@/components/cms/page/render-cms-content";

export default async function Page({ params }) {
  const sdk = getSdk();
  const page = await sdk.unifiedAlokaiCms.getPage({ path: `/${params.slug}` });

  if (!page) return notFound();

  return (
    <>
      {page.zones.componentsAboveFold && <RenderCmsContent item={page.zones.componentsAboveFold} />}
      {page.zones.componentsBelowFold && <RenderCmsContent item={page.zones.componentsBelowFold} />}
    </>
  );
}

Environment variables reference

Variable	Required	Description
`ALOKAI_CMS_BASE_URL`	Yes	URL of your Alokai CMS worker
`ALOKAI_CMS_SPACE`	Yes	Space ID from the CMS dashboard
`ALOKAI_CMS_EDITION`	No	Edition name (default: `main`)
`ALOKAI_CMS_TOKEN`	No	API key for authenticated requests