Unifying the integration

This guide will walk you through the process of unifying the integration.

Generating integration extension boilerplate is supported since @alokai/cli@v2.1.0.

Prerequisites

You need to have a custom integration created. If you don't have one, you can create one by following the quick start guide.

The unification process has been described in detail in the Unified Data Model documentation.

Generating the integration extension boilerplate

To generate the integration extension boilerplate, run the following command:

yarn alokai-cli extension generate --i=<integration-name> --template=<template-name>
# Example: yarn alokai-cli extension generate --i=my-integration

Templates

The integration extension boilerplate is generated with a template. You can choose from the following templates:

unified-commerce (default)
unified-cms

The unified-commerce template is the default template and is used for unified commerce integrations. The unified-cms template is used for content management system integrations, enabling reuse of existing CMS components.

Custom Alokai Integration - Unified Commerce extension

This is an integration extension boilerplate for Alokai Storefront Middleware.

AI support

The integration extension boilerplate ships with instructions for AI code editors (e.g., Windsurf or Cursor).

AI-Assisted configuration

You can use your AI coding assistant to automate the configuration process. Simply ask it to:

Follow the instructions in the apps/storefront-middleware/integrations/<target_integration_name>/extensions/unified/getting-started.md file.

The AI assistant should:

Register your extension in the integration config,
Add the export statement in your SDK modules index,
Implement example usage in your components.

AI-Assisted Unified Methods implementation

You can use an AI coding assistant to automate the process of implementing unified API methods in your integration. Simply ask it to:

Follow the instructions in the apps/storefront-middleware/integrations/<target_integration_name>/extensions/unified/ai/implement-unified-method.md file.

The AI assistant should:

Suggest which base API methods to use to fetch data,
Implement data fetching using base API methods in the unified method,
Implement normalizers used in the unified method.

Configuration

Registering extension

The extension is not automatically registered in your integration's configuration. Register it manually in the apps/storefront-middleware/integrations/<target_integration_name>/config.ts file:

+ import { unifiedApiExtension } from './extensions/unified';

export const config = {
  // ...other config properties
  extensions: (existing: ApiClientExtension[]) => [
    ...existing,
    // ...other extensions
+   unifiedApiExtension
  ],
} satisfies Integration<Config>;

Registering SDK module

The SDK module added when installing the extension is not automatically registered in your SDK configuration. Register it by exporting it manually from the apps/storefront-unified-nextjs/modules/index.ts file:

+ export * from '@/sdk/modules/unified-<target_integration_name>';

Usage

Run your Next.js application using yarn dev
Call your integration's unified SDK module in any of your components, e.g. /apps/storefront-unified-nextjs/app/[locale]/layout.tsx:

// Assuming <target_integration_name> is "boilerplate"
export default async function RootLayout({ children, params: { locale } }: RootLayoutProps) {
+ const sdk = await getSdk();

+ sdk.unifiedBoilerplate.getProductDetails({ id: "1" });

  return ( ... );
}

Verify that the following logs appear in the terminal:

storefront-middleware-default:dev: mocked unified getProductDetails method has been called with args: { id: '1' }