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)
@vsf-enterprise/alokon-api package available in your registry

Setup

Install the API package
Terminal window
```
yarn add @vsf-enterprise/alokon-api
```

Add the middleware integration

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

import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
import type { MiddlewareConfig } from '@vsf-enterprise/alokon-api';

const {
  ALOKON_BASE_URL = 'http://localhost:8787',
  ALOKON_ENVIRONMENT = 'main',
  ALOKON_SPACE,
  ALOKON_TOKEN,
} = process.env;

export const config = {
  configuration: {
    baseUrl: ALOKON_BASE_URL,
    environment: ALOKON_ENVIRONMENT,
    space: ALOKON_SPACE,
    token: ALOKON_TOKEN,
  },
  location: '@vsf-enterprise/alokon-api/server',
} satisfies Integration<MiddlewareConfig>;

Then register it in middleware.config.ts:

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

export default {
  integrations: {
    // ... other integrations
    alokon: cmsConfig,
  },
};

Add the SDK module

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

import { defineSdkModule } from '@vue-storefront/next';
import type { UnifiedAlokonEndpoints } from 'storefront-middleware/types';

export const unifiedAlokon = defineSdkModule(({ buildModule, config, getRequestHeaders, middlewareModule }) =>
  buildModule(middlewareModule<UnifiedAlokonEndpoints>, {
    apiUrl: `${config.apiUrl}/alokon/unified`,
    ssrApiUrl: `${config.ssrApiUrl}/alokon/unified`,
    defaultRequestConfig: {
      headers: getRequestHeaders(),
    },
  }),
);

import { unifiedAlokon } from './modules/unified-cms-alokon';

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

Set environment variables

Add to your middleware .env:

ALOKON_BASE_URL=https://your-cms.workers.dev
ALOKON_SPACE=your-space-id
ALOKON_ENVIRONMENT=main
ALOKON_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.unifiedAlokon.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
`ALOKON_BASE_URL`	Yes	URL of your Alokai CMS worker
`ALOKON_SPACE`	Yes	Space ID from the CMS dashboard
`ALOKON_ENVIRONMENT`	No	Environment name (default: `main`)
`ALOKON_TOKEN`	No	API key for authenticated requests