Quick start

Prerequisites

SAP Commerce Cloud configured - before following this guide, make sure you have an already configured SAP Commerce Cloud project. It includes creating and configuring:
- at least one Website in WCMS > Websites tab,
- at least one Base Store connected to your Website in Base Commerce > Base Store tab,
- an OAuth Client in System > OAuth > OAuth Clients tab,
- a Catalog in the Catalog > Catalogs tab,
- a Catalog version in the Catalog > Catalog Versions tab.
Install Node.js version 22.
Standard Alokai Enterprise Storefront installation

Adding the integration

In this guide, we will explain how to add the SAPCC integration to your Storefront application.

Middleware

Install SAPCC integration, in the storefront-middleware application:

Install the SAP Commerce Cloud API Client. This package is used to create a connection with the SAP Commerce Cloud backend and build endpoints for the server middleware.

yarn add @vsf-enterprise/sapcc-api

In the apps/storefront-middleware/integrations/sapcc directory, add a config.ts file with the following content. The file contains the configuration for the SAPCC integration. You can find more information about the configuration properties in the MiddlewareConfig API Reference.

apps/storefront-middleware/integrations/sapcc/config.ts

import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
import { AUTH_USER_TOKEN_COOKIE_NAME, type MiddlewareConfig } from '@vsf-enterprise/sapcc-api';

import { unifiedApiExtension } from '@/integrations/sapcc/extensions';

const {
  NODE_ENV,
  SAPCC_API_URI,
  SAPCC_OAUTH_CLIENT_ID,
  SAPCC_OAUTH_CLIENT_SECRET,
  SAPCC_OAUTH_TOKEN_ENDPOINT,
  SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT,
  SAPCC_OAUTH_URI,
} = process.env;

if (!SAPCC_OAUTH_URI) throw new Error('Missing env var: SAPCC_OAUTH_URI');
if (!SAPCC_OAUTH_CLIENT_ID) throw new Error('Missing env var: SAPCC_OAUTH_CLIENT_ID');
if (!SAPCC_OAUTH_CLIENT_SECRET) throw new Error('Missing env var: SAPCC_OAUTH_CLIENT_SECRET');
if (!SAPCC_OAUTH_TOKEN_ENDPOINT) throw new Error('Missing env var: SAPCC_OAUTH_TOKEN_ENDPOINT');
if (!SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT)
  throw new Error('Missing env var: SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT');
if (!SAPCC_API_URI) throw new Error('Missing env var: SAPCC_API_URI');

export const config = {
  configuration: {
    OAuth: {
      clientId: SAPCC_OAUTH_CLIENT_ID,
      clientSecret: SAPCC_OAUTH_CLIENT_SECRET,
      cookieOptions:
        NODE_ENV === 'development'
          ? {
              [AUTH_USER_TOKEN_COOKIE_NAME]: {
                sameSite: 'none',
              },
            }
          : undefined,
      tokenEndpoint: SAPCC_OAUTH_TOKEN_ENDPOINT,
      tokenRevokeEndpoint: SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT,
      uri: SAPCC_OAUTH_URI,
    },
    api: {
      baseSiteId: 'apparel-uk',
      catalogId: 'apparelProductCatalog',
      catalogVersion: 'Online',
      defaultCurrency: 'USD',
      defaultLanguage: 'en',
      uri: SAPCC_API_URI,
    },
  },
  extensions: (extensions: ApiClientExtension[]) => [
    ...extensions,
    unifiedApiExtension,
  ],
  location: '@vsf-enterprise/sapcc-api/server',
} satisfies Integration<Config>;

export type Config = MiddlewareConfig;

Update apps/storefront-middleware/middleware.config.ts to register the SAPCC integration.

apps/storefront-middleware/middleware.config.ts

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

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

export const config = {
  integrations: {
    commerce: commerceConfig,
  },
} satisfies MiddlewareConfig;

Export the Endpoints interface from storefront-middleware/types.ts. This allows the frontend SDK to be typed against the middleware endpoints.

apps/storefront-middleware/types.ts

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

Configure environment variables in your .env file.

apps/storefront-middleware/.env

SAPCC_API_URI=<base_url>/occ/v2
SAPCC_OAUTH_URI=
SAPCC_OAUTH_CLIENT_ID=
SAPCC_OAUTH_CLIENT_SECRET=
SAPCC_OAUTH_TOKEN_ENDPOINT=
SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT=

Environment variables:

In the portal, your API url can be found in Deployment > Environments > select your environment view. In the Public Endpoints table, find the row named "API" and copy its URL, and add /occ/v2 at the end. It looks like: https://api.c1jvi8hu9a-vsfspzooa1-d1-public.model-t.cc.commerce.ondemand.com/occ/v2
For infomation about SAPCC_OAUTH vars see the MiddlewareOAuthConfig API Reference

SDK

As you are using a Alokai Enterprise Storefront Application, the commerce integration is already configured in your frontend application for you. No changes are required in your frontend application. Following are some example configuations on how to use the SDK in your application.

SDK Config example

sdk/modules/commerce.ts

import { sapccModule } from '@vsf-enterprise/sapcc-sdk';
import { defineSdkModule } from '@vue-storefront/next';
import type { CommerceEndpoints } from 'storefront-middleware/types';

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

sdk/modules/unified.ts

import { sapccModule } from '@vsf-enterprise/sapcc-sdk';
import { defineSdkModule } from '@vue-storefront/next';
import type { UnifiedEndpoints } from 'storefront-middleware/types';

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

sdk/modules/index.ts

export * from './commerce';
export * from './unified';
// ... other module exports

Usage

Here's an example of how you can use the SAP Commerce Cloud SDK module in your application:

Pages Router

import { getSdk } from "@/sdk";

export function getServerSideProps() {
  const sdk = await getSdk();
  const { products } = await sdk.unified.searchProducts();

  return {
    props: {
      products,
    },
  };
}

That's it! You can now use SAPCC in your Next.js app ✨

OpenAPI SDK

Need more types? Extending the SAP Commerce Cloud integration? You might need the @vsf-enterprise/sap-commerce-webservices-sdk package, which includes the definitions of the types of SAP Commerce Webservices.