Quick start

Prerequisites

BigCommerce store configured - if you don't have BigCommerce store configured, see our BigCommerce Configuration guide.
Install Node.js version 22.
Standard Alokai Enterprise Storefront installation

Adding the integration

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

Middleware

Install BigCommerce integration, in the storefront-middleware application:

Install the API Client to communicate with BigCommerce. This package is used to create a server-to-server connection with the BigCommerce backend and build endpoints for the server middleware.

yarn add @vsf-enterprise/bigcommerce-api

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

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

import type { ApiClientExtension, Integration } from '@alokai/connect/middleware';
import {
  COOKIE_KEY_CUSTOMER_DATA,
  type MiddlewareSettingsConfig,
} from '@vsf-enterprise/bigcommerce-api';

const {
  BIGCOMMERCE_API_ACCESS_TOKEN,
  BIGCOMMERCE_API_CLIENT_ID,
  BIGCOMMERCE_API_CLIENT_SECRET,
  BIGCOMMERCE_API_URL,
  BIGCOMMERCE_CHANNEL_ID = '1',
  BIGCOMMERCE_STORE_GUEST_TOKEN,
  BIGCOMMERCE_STORE_ID,
  NODE_ENV,
} = process.env;

if (!BIGCOMMERCE_API_CLIENT_ID) throw new Error('Missing env var: BIGCOMMERCE_API_CLIENT_ID');
if (!BIGCOMMERCE_API_CLIENT_SECRET) throw new Error('Missing env var: BIGCOMMERCE_API_CLIENT_SECRET');
if (!BIGCOMMERCE_API_URL) throw new Error('Missing env var: BIGCOMMERCE_API_URL');
if (!BIGCOMMERCE_STORE_ID) throw new Error('Missing env var: BIGCOMMERCE_STORE_ID');
if (!BIGCOMMERCE_API_ACCESS_TOKEN) throw new Error('Missing env var: BIGCOMMERCE_API_ACCESS_TOKEN');
if (isNaN(parseInt(BIGCOMMERCE_CHANNEL_ID))) throw new Error('BIGCOMMERCE_CHANNEL_ID is not a number');

export const config = {
  configuration: {
    channelId: parseInt(BIGCOMMERCE_CHANNEL_ID),
    cookie_options:
      NODE_ENV === 'development'
        ? {
            [COOKIE_KEY_CUSTOMER_DATA]: {
              sameSite: 'none',
              secure: true,
            },
          }
        : {},
    jwtTokenExpirationDays: 2,
    sdkSettings: {
      accessToken: BIGCOMMERCE_API_ACCESS_TOKEN,
      apiVersion: 'v3',
      callback: BIGCOMMERCE_API_URL,
      clientId: BIGCOMMERCE_API_CLIENT_ID,
      guestToken: BIGCOMMERCE_STORE_GUEST_TOKEN,
      headers: { 'Accept-Encoding': '*' },
      logLevel: 'info',
      responseType: 'json',
      secret: BIGCOMMERCE_API_CLIENT_SECRET,
      storeHash: BIGCOMMERCE_STORE_ID,
    },
    stdTTL: 86_400,
  },
  extensions: (extensions: ApiClientExtension[]) => [...extensions],
  location: '@vsf-enterprise/bigcommerce-api/server',
} satisfies Integration<Config>;

export type Config = Partial<MiddlewareSettingsConfig>;

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

apps/storefront-middleware/middleware.config.ts

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

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

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/bigcommerce-api';

Configure environment variables in your .env file.

apps/storefront-middleware/.env

BIGCOMMERCE_API_CLIENT_ID=
BIGCOMMERCE_API_CLIENT_SECRET=
BIGCOMMERCE_API_URL=
BIGCOMMERCE_API_ACCESS_TOKEN=
BIGCOMMERCE_STORE_ID=
BIGCOMMERCE_CHANNEL_ID=1
BIGCOMMERCE_STORE_GUEST_TOKEN=

Environment variables:

BIGCOMMERCE_API_CLIENT_ID — Client ID obtained during creating an API account
BIGCOMMERCE_API_CLIENT_SECRET — Client secret obtained during creating an API account
BIGCOMMERCE_API_URL — API path obtained during creating an API account
BIGCOMMERCE_API_ACCESS_TOKEN — Access token obtained during creating an API account
BIGCOMMERCE_STORE_ID — store_hash included in API path between /stores/ and /v3/
BIGCOMMERCE_CHANNEL_ID — channel_id of the default storefront (defaults to 1)
BIGCOMMERCE_STORE_GUEST_TOKEN — Preview code from Review & test your store block

SDK

As you are using an 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 configurations on how to use the SDK in your application.

SDK Config example

sdk/modules/commerce.ts

import { defineSdkModule } from '@vue-storefront/next';
import type { CommerceEndpoints } from 'storefront-middleware/types';

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

sdk/modules/index.ts

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

Usage

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

App Router

import { getSdk } from "@/sdk";

const sdk = await getSdk();
const result = await sdk.commerce.getProductById({
  entityId: 97,
  includeModifiers: true,
  includeOptions: true,
});

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