Configuring Alokai

Before configuring your Alokai app, it's necessary to configure BigCommerce first. If you haven't done this yet, see the Configuring BigCommerce guide.

Set up environment variables

Alokai application uses the following environment variables to create a connection with BigCommerce API:

Environment variable	Description
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_STORE_GUEST_TOKEN	`Preview code` from `Review & test your store` block
BIGCOMMERCE_CHANNEL_ID	`channel_id` of the default storefront

Cookies (optional)

Some cookies are set by the middleware server and are out of the theme scope, therefore we introduce the possibility to customize its options. To override the default cookie options you must use the cookie name as a key and CookieOptions as a configuration object. The list of cookies set by the server:

customer-data - token cookie

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

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

export const config = {
  configuration: {
    cookie_options: {
      [COOKIE_KEY_CUSTOMER_DATA]: {
        httpOnly: true,
        secure: true,
        sameSite: 'lax',
      },
    },
  },
  // ... rest of the configuration
} satisfies Integration<Partial<MiddlewareSettingsConfig>>;

Overriding the default payload generation for the JWT token

You can override the default payload generation for the JWT token by adding the generateJwtPayload property to the configuration. This is useful when you need to add custom claims to the JWT token. The function should return an object with the claims to be added to the JWT token. More information about the requirements for the JWT token payload can be found in the BigCommerce documentation.

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

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

export const config = {
  configuration: {
    // ...
    generateJwtPayload: ({
      clientId,
      storeHash,
      channelId,
      customerId,
      redirectUrl,
    }) => ({
      iss: clientId,
      iat: Math.round(Date.now() / 1000),
      jti: crypto.randomUUID(), // unique identifier for the token
      operation: 'customer_login',
      store_hash: storeHash,
      channel_id: channelId,
      customer_id: customerId,
      customProperty: 'custom',
      // Other custom claims
    }),
  },
  location: '@vsf-enterprise/bigcommerce-api/server',
  // ... rest of the configuration
} satisfies Integration<Partial<MiddlewareSettingsConfig>>;