Development - Integrations Management

This guide covers how to manage different integrations across your stores in Alokai multistore projects.

What You'll Learn

• How to register different integrations for specific stores
• How to match store IDs with CMS spaces
• Best practices for integration management

Using Different Integration in Each Store

In Alokai multistore projects, each store can use different integrations by overriding the default middleware and SDK configurations. The base configuration is defined in the root apps, and each store can override it by providing its own configuration files.

To use a different integration in a specific store:

1. Register the integration in the store's middleware by defining its configuration and exporting its types.

Example of the config file:

import { type MiddlewareConfig } from "@vsf-enterprise/sapcc-api";
// ... other imports

export const config = {
  configuration: {
    // ...
  },

  extensions: (extensions: ApiClientExtension[]) => [
    ...extensions,
    unifiedApiExtension,
    // ...
  ],

  location: "@vsf-enterprise/sapcc-api/server",
} satisfies Integration<Config>;

export type Config = MiddlewareConfig;

Example of the types file:

export type {
  CheckoutEndpoints,
  CustomEndpoints,
} from "@/integrations/sapcc/extensions";

export type {
  Endpoints as CommerceEndpoints,
  SapccIntegrationContext as IntegrationContext,
} from "@vsf-enterprise/sapcc-api";

export type { Endpoints as UnifiedEndpoints } from "@vsf-enterprise/unified-api-sapcc";

2. Configure the middleware to use the integration by overriding the middleware.config.ts file. Example:

import "dotenv/config";

import { config as commerceConfig } from "@/integrations/sapcc";

export const config = {
  integrations: {
    commerce: commerceConfig,
    // ...
  },
};

3. (Optional) Register the SDK module in the store's frontend. This step is only required if an integration has its own SDK module. Example:

import { sapccModule } from "@vsf-enterprise/sapcc-sdk";
import { defineSdkModule } from "@vue-storefront/next";

export const commerce = defineSdkModule(
  ({ buildModule, config, getRequestHeaders }) =>
    buildModule(sapccModule, {
      apiUrl: `${config.apiUrl}/commerce`,
      cdnCacheBustingId: config.cdnCacheBustingId,
      defaultRequestConfig: {
        headers: getRequestHeaders(),
      },
      ssrApiUrl: `${config.ssrApiUrl}/commerce`,
    })
);

That's it! Once these steps are completed, the integration will be properly registered and available in both the middleware and storefront applications for that specific store.

Matching Store with CMS Space

When working with CMS integrations in a multistore setup, we recommend using a single CMS instance with multiple spaces, where each space corresponds to a different store. This approach provides better organization and separation of content while maintaining a unified CMS infrastructure.

To use different CMS spaces per store, make sure each of the stores can use a different space ID by storing it as an environment variable:

// <store>/storefront-middleware/.env.example
// ... other env variables
CMS_SPACE_ID="your-store-specific-space-id"

Finally, make sure the variable is referenced in the CMS integration config file:

import type { MiddlewareConfig } from '@vsf-enterprise/contentful-api';

export const config = {
  configuration: {
    space: process.env.CMS_SPACE_ID,
    // ... other configuration
  },
  extensions: (extensions: ApiClientExtension[]) => [
    ...extensions,
    // ... other extensions
  ],
  location: '@vsf-enterprise/contentful-api/server',
} satisfies Integration<MiddlewareConfig>;

This way, each store will have its own CMS space, and the content will be properly separated and organized.