Vue Storefront is now Alokai! Learn More
Configuration

Configuration

Server middleware

To configure the SalesForce Commerce Cloud server middleware integration, you need to prepare the middleware.config.js file. It's a JavaScript file that exports a configuration object. The configuration object has the following properties:

module.exports = {
  integrations: {
    sfcc: {
      location: "@vsf-enterprise/sfcc-api/server",
      configuration: {
        cache: process.env.SFCC_CACHE !== "false",
        timeout: process.env.SFCC_TIMEOUT || 10000,
        origin: process.env.SFCC_ORIGIN,
        siteId: process.env.SFCC_SITE_ID,
        scapiClientId: process.env.SFCC_SCAPI_CLIENT_ID,
        slasClientId: process.env.SFCC_SLAS_CLIENT_ID,
        slasClientSecret: process.env.SFCC_SLAS_CLIENT_SECRET,
        ocapiClientId: process.env.SFCC_OCAPI_CLIENT_ID,
        scapiClientSecret: process.env.SFCC_SCAPI_CLIENT_SECRET,
        ocapiClientSecret: process.env.SFCC_OCAPI_CLIENT_SECRET,
        ocapiVersion: process.env.SFCC_OCAPI_VERSION,
        commerceApiVersion: process.env.SFCC_SCAPI_VERSION || "v1",
        shortCode: process.env.SFCC_SHORT_CODE,
        organizationId: process.env.SFCC_ORGANIZATION_ID,
        viewType: process.env.SFCC_PRODUCT_IMAGE_VIEW_TYPE,
        ocapiEndpoints: {
          updatePaymentInstrumentInBasket: true, // The SCAPI method is broken
        },
        cookieNames: {
          siteId: process.env.SFCC_COOKIES_SITE_ID || "vsf-sfcc-site-id",
          amAuthToken: process.env.SFCC_COOKIES_AM_TOKEN || "vsf-sfcc-am-token",
          scapiAuthToken:
            process.env.SFCC_COOKIES_SCAPI_TOKEN || "vsf-sfcc-scapi-token",
          scapiRefreshToken:
            process.env.SFCC_COOKIES_SCAPI_REFRESH_TOKEN ||
            "vsf-sfcc-scapi-refresh-token",
          ocapiAuthToken:
            process.env.SFCC_COOKIES_OCAPI_TOKEN || "vsf-sfcc-ocapi-token",
          currency: process.env.SFCC_COOKIES_CURRENCY || "vsf-sfcc-currency",
          locale: process.env.SFCC_COOKIES_LOCALE || "vsf-sfcc-locale",
          usid: process.env.SFCC_COOKIES_USID || "vsf-sfcc-usid",
        },
        clientHeaders: {
          siteId:
            process.env.SFCC_CLIENT_HEADERS_SITE_ID || "x-vsf-sfcc-site-id",
          amAuthToken:
            process.env.SFCC_CLIENT_HEADERS_AM_TOKEN || "x-vsf-sfcc-am-token",
          scapiAuthToken:
            process.env.SFCC_CLIENT_HEADERS_SCAPI_TOKEN ||
            "x-vsf-sfcc-scapi-token",
          scapiRefreshToken:
            process.env.SFCC_CLIENT_HEADERS_SCAPI_REFRESH_TOKEN ||
            "x-vsf-sfcc-scapi-refresh-token",
          ocapiAuthToken:
            process.env.SFCC_CLIENT_HEADERS_OCAPI_TOKEN ||
            "x-vsf-sfcc-ocapi-token",
          currency:
            process.env.SFCC_CLIENT_HEADERS_CURRENCY || "x-vsf-sfcc-currency",
          locale: process.env.SFCC_CLIENT_HEADERS_LOCALE || "x-vsf-sfcc-locale",
          usid: process.env.SFCC_CLIENT_HEADERS_USID || "x-vsf-sfcc-usid",
        },
        callbacks: {
          auth: {
            onPasswordResetTokenGenerated({ token, email, login, phone, siteId, customerId, codeVerifier }) {
              // This is an example implementation for demo purposes.
              // In a real scenario, the token should be sent to the customer here (e.g. an email and phone are available in the payload),
              // and the token MUST NOT be exposed to the client
              return { token, email, login, phone, siteId, customerId, codeVerifier };
            },
          },
        },
      },
    },
  },
};

Let's go through the configuration properties one by one.

cache

If set to false an additional timestamp parameter is added to all API GET calls to prevent caching.

timeout

Time in ms to wait for a response from the API calls. Default: 10000.

origin

The base URL of the API.

siteId

The site ID for the storefront. This is the name of the site (sometimes called a “channel”) for which you want to access data.

For example: RefArch or SiteGenesis.

To see a list of sites in Business Manager:

  • Go to the Business Manager URL for your instance.
  • Log in using your Account Manager credentials.
  • Go to Administration > Sites > Manage Sites.

To learn more about site names, see the B2C Commerce documentation.

scapiClientId

The client ID for the Salesforce Commerce API (SCAPI) application.

For authentication, an Account Manager administrator provisions a new client in the Account Manager with client credentials.

Unlike with user authentication, you can provision OCAPI clients only in Account Manager, which enables them to authenticate against any Business Manager instance in the organization.

scapiClientSecret

The secret of the client used for the Salesforce B2C Commerce Open Commerce API (OCAPI) application.

slasClientId

The client ID of a private SLAS client that will be used for customer authentication through SCAPI - Setup instructions.

Note: If an OCAPI key is in use, it's recommended to have this be the same (the client ID value can be set manually during creation). This will allow for interoperability between SCAPI and OCAPI on persistent objects such as carts and baskets that are owned by guests, since it would allow both API families to share the same JWT for authentication, and by extension - the same guest customer ID.

slasClientSecret

The client secret of a private SLAS client that will be used for customer authentication through SCAPI - Setup instructions.

ocapiClientId

The client ID for the Salesforce B2C Commerce Open Commerce API (OCAPI) application.

ocapiClientSecret

The secret of the client used for the Salesforce B2C Commerce Open Commerce API (OCAPI) application.

ocapiVersion

The version of the Salesforce B2C Commerce OCAPI.

commerceApiVersion

The version of the Salesforce B2C Commerce Commerce API.

shortCode

The storefront's short code. The short code is an eight-character string that is assigned to a realm for routing purposes.

The short code applies to your entire realm, across all instances.

The short code is in the same place as the organization ID. To look it up:

  • Go to the Business Manager URL for your instance.
  • Log in using your Account Manager credentials.
  • Go to Administration > Site Development > Salesforce Commerce API Settings.

If you’ve never used the B2C Commerce API in your realm, click Request Short Code to request one.

organizationId

The organization ID is a short string that identifies a B2C Commerce instance.

Each instance gets its own unique organization ID, such as f_ecom_zzte_053.

viewType

The view type for the storefront as defined in the master catalog.

ocapiEndpoints

Which OCAPI endpoints to enable or disable.

jwtEncryption

Can be used to provide additional security by applying hybrid encryption on authentication tokens before they are returned to the client. If the configuration is provided, first a random 32-byte encryption key and initialization vector will be generated, which will be used to symmetrically encrypt the JWT using the aes-256-gcm algorithm. The provided key pair will then be used to asymmetrically encrypt the key and IV via public/private RSA encryption. When an encrypted value is sent by the client in place of a JWT, the reverse process will take place.

The expected format is a 2048-bit key pair. One can be generated with e.g. the following commands:

openssl genpkey -algorithm RSA -out private-key.pem
openssl rsa -pubout -in private-key.pem -out public-key.pem

The resulting keys can then be provided to the middleware as follows:

jwtEncryption: {
    publicKey: fs.readFileSync('./public-key.pem').toString(),
  privateKey: fs.readFileSync('./private-key.pem').toString()
}

In production a secret management service should be used to fetch the key instead.

NOTE: This process significantly increases the size of the data that gets sent back to the client. This can lead to a situation where Node's header size limit (16kb) is reached, causing a 500 response. The limit can be adjusted using the --max-http-header-size CLI parameter. If adjusting the limit is not possible, using only OCAPI or SCAPI rather than both in parallel is advised.

cookieNames

The names of the cookies for the Salesforce B2C Commerce JSON web tokens.

clientHeaders

Custom headers to send with every API request.

callbacks

Callbacks that will be used for state changes within the client's lifecycle.

SDK module

To configure the SalesForce Commerce Cloud SDK module, you need to initialize the module with following configuration:

import Cookie from "cookie-universal";
import { buildModule, initSDK } from "@vue-storefront/sdk";
import { sfccModule } from "@vsf-enterprise/sfcc-sdk";

const cookie = Cookie();
const getCookie = (name: string) => cookie.get(name);
const setCookie = (name: string, value: string) => cookie.set(name, value);

export const sdk = initSDK({
  commerce: buildModule(sfccModule, {
    apiUrl: "http://localhost:8181/sfcc",
    ssrApiUrl: "http://localhost:8181/sfcc",
    clientConfig: {
      getCookie,
      setCookie,
      cookieNames,
      clientHeaders,
    },
  }),
});

Let's go through the configuration properties one by one.

apiUrl

The base URL of the API - the server middleware.

ssrApiUrl

The base URL of the API but used for server-side rendering.

clientConfig

The client configuration object.

clientConfig.getCookie

A function that returns a cookie value by name.

clientConfig.setCookie

A function that sets a cookie value by name.

clientConfig.cookieNames

The names of the cookies for the Salesforce B2C Commerce JSON web tokens. The same as defined in the server middleware configuration.

clientConfig.clientHeaders

Custom headers to send with every API request. The same as defined in the server middleware configuration.

logLevel

Possible log level descriptors, may be string, lower or upper case, or number. Corresponds to the values used in the loglevel package. The available levels are:

  • trace (TRACE / 0)
  • debug (DEBUG / 1)
  • info (INFO / 2)
  • warn (WARN / 3)
  • error (ERROR / 4)
  • silent (SILENT / 5)