Unifying the integration

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:

1. Register your extension in the integration config,
2. Add the export statement in your SDK modules index,
3. 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:

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

Unit Testing

If you add unit tests to your extension, place them in an __tests__/ directory within the extension folder. Tests use Vitest which is already configured in the storefront-middleware.

Run tests:

cd apps/storefront-middleware
yarn test

Test files should use explicit vitest imports:

import { describe, expect, it, vi } from 'vitest';

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

1. Run your Next.js application using yarn dev
2. 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 ( ... );
}

3. Verify that the following logs appear in the terminal:

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

Custom Alokai Integration - Unified CMS extension

This is a CMS integration extension boilerplate for Alokai Storefront Middleware. It enables you to integrate any CMS platform while reusing existing CMS components from the Alokai accelerator.

Architecture Overview

The Unified CMS extension provides a powerful abstraction layer that:

• Normalizes CMS data to match Alokai component interfaces
• Reuses existing components from apps/storefront-unified-<framework>/components/cms/page
• Minimizes platform coupling through consistent data transformation
• Enables rapid CMS switching without frontend component changes

Key Benefits

• ✅ Component Reusability: Leverage pre-built CMS components (Hero, Banner, Gallery, etc.)
• ✅ Platform Agnostic: Works with any CMS (Storyblok, Contentful, SmartEdit, custom APIs)
• ✅ Type Safety: Full TypeScript support with automatic type inference
• ✅ Flexible Normalization: Transform any CMS data structure to component props
• ✅ Live Preview Support: Built-in extension points for CMS preview features

Prerequisites

Before implementing this extension, you must create content types in your CMS for all frontend components you plan to use.

Available Components

Please check the actual directory apps/storefront-unified-<framework>/components/cms/page for the complete list of available components. The following components include among others:

Required Content Types

1. Page Content Type: Must include:

   • componentsAboveFold: Array of component references
   • componentsBelowFold: Array of component references
   • url/slug: Page routing information

2. Component Content Types: Create a schema for each component you'll use (e.g., Hero, Banner, etc.)

📋 Detailed Schema Creation Guide: See CMS Schema Creation Guide for comprehensive instructions on creating CMS schemas for all available components, including the essential styles field for layout flexibility.

Unit Testing

If you add unit tests to your extension, place them in an __tests__/ directory within the extension folder. Tests use Vitest which is already configured in the storefront-middleware.

Run tests:

cd apps/storefront-middleware
yarn test

Test files should use explicit vitest imports:

import { describe, expect, it, vi } from 'vitest';

Configuration & Setup

The extension requires registration in both the middleware integration config and the frontend SDK modules.

📋 Complete Setup Guide: Follow ai/getting-started.md for step-by-step registration instructions and verification steps.

Implementation Guide

Manual implementation is recommended for better understanding and control of your CMS integration.

AI Assistant Support

This template includes AI-powered development assistance for rapid implementation:

1. Extension Setup: ai/getting-started.md - Register extension and configure modules
2. API Integration: ai/implement-cms-integration.md - Connect to your CMS API
3. Data Normalization: ai/implement-normalizers.md - Transform data structures if needed

Note: While AI assistance is available, manual implementation is strongly recommended to better understand platform-specific data structures and ensure proper handling of CMS nuances.

Usage

CMS Page Rendering

The CMS page rendering is already implemented in apps/storefront-unified-nextjs/app/[locale]/(cms)/[[...slug]]/page.tsx. This dynamic route automatically:

• Fetches CMS data using your registered module
• Renders components via RenderCmsContent for both above and below fold content
• Handles URL routing for CMS pages

API Integration

📋 Implementation Guide: See ai/implement-cms-integration.md for connecting your CMS API and implementing data fetching.

Component Registry

Components are automatically mapped in nextjs/components/cms/wrappers/render-cms-content.tsx:

const components: Record<string, CmsComponent> = {
  Accordion,
  Banner,
  Gallery,
  Hero,
  NewsletterBox,
  ProductList,
  // Add custom components here
};

To add custom components:

1. Create component in apps/storefront-unified-<framework>/components/cms/page/
2. Import and add to the registry
3. Create corresponding CMS schema
4. Implement normalizer if needed

Data Normalization

When CMS field structures don't match component props 1:1, use normalizers to transform the data. The extension provides a flexible normalization system that handles:

• Media transformation: Convert CMS image objects to component-expected format
• Component mapping: Transform CMS content types to frontend components
• Rich text processing: Handle platform-specific rich text formats
• Error handling: Graceful fallbacks for missing or invalid data

📋 Detailed Implementation: See ai/implement-normalizers.md for comprehensive normalizer implementation guide, including platform-specific examples and testing strategies.

Schema Creation Guide

For detailed instructions on creating CMS schemas for all components, including the essential styles field, see:

create-cms-schemas.md - Complete manual guide covering:

• Step-by-step schema creation for all platforms
• Reusable styles field implementation
• Testing and verification checklists

Example schema templates can also be found in your project's temp directory during development.

Development Workflow

1. Design your page structure and components in the CMS
2. Create content type schemas matching component props
3. Implement normalizers for any data transformation needed
4. Test component rendering and data flow
5. Deploy and configure live preview if supported by your CMS

Testing Your Implementation

After completing all setup steps, test your integration:

1. Component Rendering Test

1. Navigate to your test page (e.g., /test) in the browser
2. Verify that components render correctly
3. Check that content from CMS appears as expected

2. Responsive Styling Test

1. Test responsive styling across different screen sizes
2. Verify that styling changes in CMS appear on the frontend
3. Check browser dev tools for generated CSS classes

3. Debug Common Issues

1. Check console for any data processing errors
2. Verify component mapping - ensure that all components are rendered
3. Test API connectivity - confirm CMS data is being fetched

Troubleshooting

Component not rendering?

• Check component is imported and registered in the components registry
• Verify the component field in normalized data matches a key in RenderCmsContent component

Data not displaying correctly?

• Review normalizer implementation for the component
• Check CMS field names match expected component props
• Validate media normalization for image fields

Styles not applying?

• Verify styles field structure matches resolveStyles expectations
• Check that resolutions object contains min/max pixel values
• Confirm style properties use correct naming (camelCase in CMS, converts to kebab-case CSS)

Additional Resources

• CMS Modules Guide