The Vue Storefront Essentials Course is now available! Learn More
Quick start

Quick start

This guide is written for Vue Storefront Enterprise Storefront Applications. If you are using a custom setup, please refer to the Custom Installation guide.

Prerequisites

  • SAP Commerce Cloud configured - if you don't have your SAP Commerce Cloud configured, see our Configuration guide.
  • Install Node.js version >= 16.0 and < 19.0.
  • Standard Vue Storefront Enterprise Storefront installation - if you project does not use Storefront, see our Custom Installation guide.

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:

  1. 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.

Middleware directory

If you don't have apps/storefront-middleware directory, you are likely using a custom setup. Please refer to the Custom Installation guide.

yarn
yarn add @vsf-enterprise/sapcc-api
  1. In the apps/storefront-middleware/config directory, add a sapcc.config.ts file with the following content. The file contains the configuration for the SAPCC integration. You can find more information about the configuration in the Configuration guide.
apps/storefront-middleware/config/sapcc.config.ts
/* eslint-disable complexity */
import { MiddlewareConfig } from "@vsf-enterprise/sapcc-api";
import { Integration } from "@vue-storefront/middleware";

export function getSapccConfig() {
  const {
    SAPCC_OAUTH_URI,
    SAPCC_OAUTH_CLIENT_ID,
    SAPCC_OAUTH_CLIENT_SECRET,
    SAPCC_OAUTH_TOKEN_ENDPOINT,
    SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT,
    SAPCC_API_URI,
    NODE_ENV,
  } = 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");

  return {
    location: "@vsf-enterprise/sapcc-api/server",
    configuration: {
      OAuth: {
        uri: SAPCC_OAUTH_URI,
        clientId: SAPCC_OAUTH_CLIENT_ID,
        clientSecret: SAPCC_OAUTH_CLIENT_SECRET,
        tokenEndpoint: SAPCC_OAUTH_TOKEN_ENDPOINT,
        tokenRevokeEndpoint: SAPCC_OAUTH_TOKEN_REVOKE_ENDPOINT,
        cookieOptions: {
          "vsf-sap-token": { secure: NODE_ENV !== "development" },
        },
      },
      api: {
        uri: SAPCC_API_URI,
        baseSiteId: "apparel-uk",
        catalogId: "apparelProductCatalog",
        catalogVersion: "Online",
        defaultLanguage: "en",
        defaultCurrency: "USD",
      },
    },
  } satisfies Integration<MiddlewareConfig>;
}
  1. Now export the SAPCC integration config in the storefront-middleware/config/index.ts file. This allows you to use the SAPCC integration and other integrations you might add in your middleware config from a single file.
apps/storefront-middleware/config/index.ts
export * from "./sapcc.config";
  1. Update apps/storefront-middleware/middleware.config.ts file. This file contains the configuration for the middleware. In this file, you will add the SAPCC integration config to the integrations config commerce section. You will also add the image transformation function to the Unified API extension config. This function is used to transform the image URLs in the SAPCC responses to the correct format.
apps/storefront-middleware/middleware.config.ts
import { getSapccConfig } from "./config";
...

//add SAPCC_MEDIA_HOST to env variables
const { ..., SAPCC_MEDIA_HOST } = process.env;
...
// add image transformation function to unified api extension config
const unifiedApiExtension = createUnifiedExtension<Context, Config>()({
  // ...
  config: {
    transformImageUrl: (url) => {
      if (SAPCC_MEDIA_HOST) {
        return new URL(url, SAPCC_MEDIA_HOST).toString();
      }

      const [imagePathWithoutParams, searchParams = ""] = url.split("?");
      const segmentsParameter = imagePathWithoutParams.split("/").filter(Boolean);
      const sapContextSearchParameter = new URLSearchParams(searchParams).get("context");

      return `sap/${segmentsParameter}/context/${sapContextSearchParameter}`;
    },
    ...
  },
});

// add SAPCC integration config to integrations config commerce section
const config = {
  integrations: {
  //    ...,
      unified: {
      ...getSapccConfig(),
      extensions: (extensions: ApiClientExtension[]) => [...extensions, unifiedApiExtension],
    },
  },
};
  1. Configure environment variables in your .env file.
server/.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:

SDK

As you are using a Vue Storefront 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

storefront-unified-nextjs/sdk/sdk.config.ts
import { unifiedModule } from '@vsf-enterprise/unified-sdk';
import { CreateSdkOptions, createSdk } from '@vue-storefront/next';
import { UnifiedApiExtension } from 'storefront-middleware/middleware.config';

if (!process.env.NEXT_PUBLIC_API_BASE_URL) {
  throw new Error('NEXT_PUBLIC_API_BASE_URL is required to run the app');
}

const options: CreateSdkOptions = {
  middleware: {
    apiUrl: process.env.NEXT_PUBLIC_API_BASE_URL,
  },
  multistore: {
    enabled: process.env.NEXT_PUBLIC_MULTISTORE_ENABLED === 'true',
  },
};

export const { getSdk } = createSdk(options, ({ buildModule, middlewareUrl, getRequestHeaders }) => ({
  unified: buildModule(unifiedModule<UnifiedApiExtension>, {
    apiUrl: `${middlewareUrl}/unified`,
    requestOptions: {
      headers: () => getRequestHeaders(),
    },
  })
  ...
}));

export type Sdk = ReturnType<typeof getSdk>;

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.config";

export function getServersideProps() {
  const sdk = 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.