Quick start

Prerequisites

Commercetools configured - if you don't have your Commercetools configured, see our Configuration guide.
Install Node.js version 20.x or >= 22.14.0

Using the integration

In this section, we will explain in a step-by-step guide how to use Commercetools integration in your front-end application.

Middleware preparation

Key concept - Middleware

Middleware concept is described in detail in our Key concepts: Middleware docs.

In your middleware project directory, install the API Client to communicate with Commercetools. This package is used to create a server-to-server connection with the Commercetools backend and the server middleware.

yarn add @vsf-enterprise/commercetools-api

In the same middleware directory, install the @alokai/connect package. This package is used to create the server middleware.

yarn add @alokai/connect

Create a file middleware.config.ts with server middleware configuration.

// middleware.config.ts

import type { MiddlewareConfig } from '@alokai/connect/middleware';

export const config = {
  integrations: {
    ct: {
      location: '@vsf-enterprise/commercetools-api/server',
      configuration: {
        api: {
          uri: process.env.COMMERCETOOLS_API_URI,
          authHost: process.env.COMMERCETOOLS_AUTH_HOST,
          projectKey: process.env.COMMERCETOOLS_PROJECT_KEY,
          clientId: process.env.COMMERCETOOLS_CLIENT_ID,
          clientSecret: process.env.COMMERCETOOLS_CLIENT_SECRET,
          scopes: [
            `create_anonymous_token:${process.env.COMMERCETOOLS_PROJECT_KEY}`,
            `view_categories:${process.env.COMMERCETOOLS_PROJECT_KEY}`,
            `view_products:${process.env.COMMERCETOOLS_PROJECT_KEY}`,
            `view_stores:${process.env.COMMERCETOOLS_PROJECT_KEY}`,
            `manage_my_profile:${process.env.COMMERCETOOLS_PROJECT_KEY}`,
            `manage_my_orders:${process.env.COMMERCETOOLS_PROJECT_KEY}`,
            `manage_my_payments:${process.env.COMMERCETOOLS_PROJECT_KEY}`,
            `manage_my_shopping_lists:${process.env.COMMERCETOOLS_PROJECT_KEY}`,
          ],
        },
        serverApi: {
          clientId: process.env.COMMERCETOOLS_CLIENT_ID_SERVER,
          clientSecret: process.env.COMMERCETOOLS_CLIENT_SECRET_SERVER,
          scopes: [
            `manage_customers:${process.env.COMMERCETOOLS_PROJECT_KEY}`,
            `manage_products:${process.env.COMMERCETOOLS_PROJECT_KEY}`,
          ],
          operations: [],
        },
        /* Below is just an example configuration for currencies and languages */
        currency: 'USD',
        country: 'US',
        languageMap: {
          en: ['en', 'de'],
          de: ['de', 'en'],
        },
      },
    },
  },
} satisfies MiddlewareConfig;

Configure environment variables in your .env file.

# .env
# The name of your commercetools project
COMMERCETOOLS_PROJECT_KEY=

# URL of the GraphQL API
COMMERCETOOLS_API_URI=
# URL of the Auth server
COMMERCETOOLS_AUTH_HOST=
# Unique ID specific to the API client.
COMMERCETOOLS_CLIENT_ID=
# Unique secret string specific to the API client.
COMMERCETOOLS_CLIENT_SECRET=

# The serverApi object contains the information necessary to request data from the GraphQL API
# with elevated permissions that users should not have.
COMMERCETOOLS_CLIENT_ID_SERVER=
COMMERCETOOLS_CLIENT_SECRET_SERVER=

# List of allowed origins separated by coma.
# Example: MIDDLEWARE_ALLOWED_ORIGINS=http://localhost:3000,https://mydomain.io
MIDDLEWARE_ALLOWED_ORIGINS=

Create an index.ts file. This script is used to run the server middleware.

// index.ts

import { createServer } from '@alokai/connect/middleware';
import { config } from './middleware.config';

(async () => {
  const app = await createServer(config);
  const host = process.argv[2] ?? '0.0.0.0';
  const port = Number(process.argv[3] ?? 8181);

  app.listen(port, host, () => {
    console.log(`Middleware started: ${host}:${port}`);
  });
})();

Your middleware is ready. You can start it by running npx tsx index.ts

SDK preparation

Key concept - SDK

SDK is described in detail in our Key concepts: SDK docs.

In your frontend project directory, install the SDK package. It's the core of the SDK.

yarn add @alokai/connect

In the same frontend directory, install the Commercetools module. It extends the SDK core with methods to communicate with Commercetools.

yarn add @vsf-enterprise/commercetools-sdk

Initialize the SDK. Configure Commercetools module with apiUrl that points to the server middleware.

import { initSDK, buildModule } from '@alokai/connect/sdk';
import { ctModule } from '@vsf-enterprise/commercetools-sdk';

const sdkConfig = {
  ct:
    buildModule(
      ctModule,
      {
        apiUrl: 'http://localhost:8181/ct',
        ssrApiUrl: 'http://localhost:8181/ct'
      }
    )
};

export const sdk = initSDK(sdkConfig);

Your SDK is ready and you can call methods with sdk.ct.<METHOD_NAME>. To see a full list of methods offered by the Commercetools module, check out the API Reference.