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.

Prerequisitesri:link

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 boilerplateri:link

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

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

Templatesri:link

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 extensionri:link

This is an integration extension boilerplate for Alokai Storefront Middleware.

AI supportri:link

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

AI-Assisted configurationri:link

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 implementationri:link

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.

Configurationri:link

Registering extensionri:link

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 moduleri:link

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>';

Usageri:link

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' }