Documentation

Installing the Frontend SDK

Learn about installing the Frontend SDK.

The Frontend SDK, its integrations, components, and dependencies are ready to use out-of-the-box and should not require further installation.

To confirm the SDK's setup within your project repository, inspect the sdk directory located at the one of the following paths:

  • For B2B projects: packages/PROJECT_NAME/frontend/src/sdk/
  • For B2C projects: packages/PROJECT_NAME/frontend/sdk/

The presence of this directory indicates that your project includes the SDK. By default, this folder should contain the following files:

  • index.ts
  • CommercetoolsSDK.ts template
  • composable-commerce folder for B2C projects
  • composable-commerce-b2b folder for B2B projects

If the directory is not present in your commercetools Frontend project, you can install and configure the 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.