Installing the Frontend SDK

Install the SDK

To install the SDK, follow these steps:

1. Install the base SDK npm package in your commercetools Frontend project by running yarn add @commercetools/frontend-sdk in the project directory.
   We recommend installing the latest version of this package to ensure you get all features and full compatibility with your integrations.

2. The Composable Commerce integration, config, and template files are distributed as editable code, and set up within an sdk folder. Download the code from one of the following:

   • B2C projects: download the components repository from the sdk folder.
   • B2B projects: download the components-b2b repository from the src/sdk folder.

3. Import and configure the SDK in an index location within your project. The SDK.configure method needs to be called only once because the SDK is exported as a singleton. However, the SDK must be configured for both client-side and server-side rendering.

   The following examples import and configure the SDK in a Next.js 12 project.

   For client-side configuration, add the below to your packages/PROJECT_NAME/frontend/pages/_app.tsx file.

   packages/PROJECT_NAME/frontend/pages/_app.tsxTypeScript React

   import { AppProps } from 'next/app';
   import { useRouter } from 'next/router';
   import { sdk } from '../sdk';
   
   const Starter = ({ Component, pageProps }: AppProps) => {
     const router = useRouter();
     sdk.defaultConfigure(router.locale as string);
   
     return <Component {...pageProps} />;
   };
   
   export default Starter;

   For server-side configuration, add the below to your packages/PROJECT_NAME/frontend/pages/[[...slug]].tsx file in the getServerSideProps function.

   packages/PROJECT_NAME/frontend/pages/[[...slug]].tsxTypeScript React

   import { GetServerSideProps, Redirect } from 'next';
   import { sdk } from '../sdk';
   ...
   ...
   export const getServerSideProps: GetServerSideProps | Redirect = async ({
     params, locale, query, req, res
   }) => {
     sdk.defaultConfigure(locale as string);
     ...
   };
   In Next.js 13, the client-side index location is packages/PROJECT_NAME/frontend/src/app/[locale]/[[...slug]]/page.tsx and server-side is in any of the API routes or server components.

The SDK and Composable Commerce integration is now set up.

Configure the SDK

The configure method is defined on the base SDK main class in the @commercetools/frontend-sdk library and has several optional and required properties, the required properties will already be set up in your project using the defaultConfigure method in the CommercetoolsSDK.ts template file. The configure method supports the following options:

• locale - String - Required. The combination of the language and country code in ISO 639-1 and ISO 3166-1 format respectively. For example, en-DE or en_DE. In your code, you can access the locale from the PageProps.params.locale (Next.js 12) or using the useParams() hook (Next.js 13).

• currency - String - Required. The three-letter ISO 4217 Currency Code. For example, EUR. For more information, see supported currencies.

• endpoint - String - Required. The full URL of the API hub endpoint.

• extensionVersion - String - Required. The extension bundle version to connect to.

• useCurrencyInLocale - Boolean - Optional. If true, the currency is required in the locale in the format LOCALE@CURRENCY. Defaults to false. Overrides the currency option.

• sessionLifetime - Number - Optional. This is the amount of time in milliseconds for which a user's session persists before needing to log in again. Overrides the default session lifetime of three months.

• customHeaderValue - String - Optional. This is the value sent as the coFE-Custom-Configuration header value with every request. You can override this value on a specific request by setting the customHeaderValue option in the API methods. To access this value globally, call the SDK.customHeaderValue() function.

• cookieHandlingOverride - CookieManager - Optional. This option gives the user the ability to extend or override the default base SDK's CookieHandler.
  The following code example shows how to extend the default cookie handling using the defaultConfigure method in the SDK template file.

  Example code to specify custom cookie handling logicTypeScript

  import { sdk } from 'src/sdk';
  import { CookieHandler, ServerOptions } from '@commercetools/frontend-sdk';
  
  const cookieHandler = new CookieHandler();
  
  sdk.configure({
    ...
    cookieHandlingOverride: {
      setCookie: async (key: string, data: any, options?: ServerOptions) => {
        cookieHandler.setCookie(key, data, options);
      },
      getCookie: async (key: string, options?: ServerOptions) => {
        return cookieHandler.getCookie(key, options);
      },
      getCookies: async (options?: ServerOptions) => {
        return cookieHandler.getCookies(options);
      },
      deleteCookie: async (key: string, options?: ServerOptions) => {
        return cookieHandler.deleteCookie(key, options);
      },
      hasCookie: async (key: string, options?: ServerOptions) => {
        return cookieHandler.hasCookie(key, options);
      },
    },
  });

• redactionHandlingOverride - RedactionManager and RedactionManagerConfig - Optional. This option lets the user override the default redaction behavior of the base SDK's events, such as redacting passwords from event properties and URL parameters.

  You can extend or override the default functionality by passing a class or object that implements the RedactionManager interface.
  You can override the default redaction rules by passing a RedactionManagerConfig object.

  The following code example shows how to extend or override the default redaction handling methods using the defaultConfigure method in the SDK template file.

  Example of custom redaction handling logicTypeScript

  import { sdk } from 'src/sdk';
  import { RedactionHandler, ServerOptions } from '@commercetools/frontend-sdk';
  
  const redactionHandler = new RedactionHandler();
  
  sdk.configure({
    ...
    redactionHandlingOverride: {
      redact: async <T>(data: T) => {
        return redactionHandler.redact(data);
      },
      redactUrl: async (url: string) => {
        return redactionHandler.redactUrl(data);
      }
    },
  });

  The following code example shows how to override the default redaction handling configuration using the defaultConfigure method in the SDK template file.

  Example code to specify custom redaction handling configurationTypeScript

  import { sdk } from 'src/sdk';
  import { RedactionManagerConfig, ServerOptions } from '@commercetools/frontend-sdk';
  
  const customRedactConfig: RedactionManagerConfig = {
    paths: [{ value: "my.path.toRedact", caseSensitive: true }],
    properties: [],
    whitelistPaths: [{ "my.non_sensitive.password", caseSensitive: true }],
    includes: [{ value: "password" }, { value: "token" }],
    jsonRedactionText: "<CUSTOM_REDACT_TEXT>",
    urlRedactionText: "CUSTOM_URL_REDACT_TEXT",
  }
  
  sdk.configure({
    ...
    redactionHandlingOverride: customRedactConfig,
  });