Quick start

Prerequisites

BigCommerce store configured - if you don't have BigCommerce store configured, see our BigCommerce Configuration guide.
Install Node.js version 16.0

Using the integration

In this section, we will explain in a step-by-step guide how to use BigCommerce integration in your front-end application.

Middleware preparation

Key concept - Middleware

Middleware concept is described in detail in our Key concepts: Middleware docs.

Already have the server middleware configured?

If you have the server middleware configured, you can move directly to the SDK preparation part.

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

yarn add @vsf-enterprise/bigcommerce-api

Install @vue-storefront/middleware package. This package is used to create the server middleware.

yarn add @vue-storefront/middleware

Create a file middleware.config.ts with server middleware configuration.

// middleware.config.ts

require("dotenv").config();

export const integrations = {
  bigcommerce: {
    location: "@vsf-enterprise/bigcommerce-api/server",
    configuration: {
      sdkSettings: {
        logLevel: "info",
        clientId: process.env.BIGCOMMERCE_API_CLIENT_ID,
        secret: process.env.BIGCOMMERCE_API_CLIENT_SECRET,
        callback: process.env.BIGCOMMERCE_API_URL,
        storeHash: process.env.BIGCOMMERCE_STORE_ID,
        accessToken: process.env.BIGCOMMERCE_API_ACCESS_TOKEN,
        guestToken: process.env.BIGCOMMERCE_STORE_GUEST_TOKEN,
        responseType: "json",
        headers: { "Accept-Encoding": "*" },
        graphqlMaxRetry: Number(process.env.GRAPHQL_MAX_RETRY),
      },
      jwtTokenExpirationDays: 2,
      stdTTL: 86400,
      cookie_options: {
        "customer-data": {
          httpOnly: true,
          secure: true,
          sameSite: "None",
        },
      },
      // @deprecated - use cookie_options instead.
      secureCookies: process.env.NODE_ENV === "production",
    },
  },
};

Configure environment variables in your .env file.

# .env
BIGCOMMERCE_API_CLIENT_ID=
BIGCOMMERCE_API_CLIENT_SECRET=
BIGCOMMERCE_API_URL=
BIGCOMMERCE_API_ACCESS_TOKEN=
DEFAULT_CHANNEL_ID=
BIGCOMMERCE_STORE_ID=
GRAPHQL_MAX_RETRY=

Create a middleware.js file. This script is used to run the server middleware.

// middleware.js

const { createServer } = require("@vue-storefront/middleware");
const { integrations } = require("./middleware.config");
const cors = require("cors");

(async () => {
  const app = await createServer({ integrations });
  // By default it's running on the localhost.
  const host = process.argv[2] ?? "0.0.0.0";
  // By default it's running on the port 8181.
  const port = process.argv[3] ?? 8181;
  const CORS_MIDDLEWARE_NAME = "corsMiddleware";

  const corsMiddleware = app._router.stack.find(
    (middleware) => middleware.name === CORS_MIDDLEWARE_NAME
  );

  // You can overwrite the cors settings by defining allowed origins.
  corsMiddleware.handle = cors({
    origin: ["http://localhost:3000"],
    credentials: true,
  });

  app.listen(port, host, () => {
    console.log(`Middleware started: ${host}:${port}`);
  });
})();

Your middleware is ready. You can start it by running node middleware.js

SDK preparation

Key concept - SDK

SDK is described in detail in our Key concepts: SDK docs.

Install the SDK package. It's the core of the SDK.

yarn add @vue-storefront/sdk

Initialize the SDK. Configure BigCommerce module with apiUrl that points to the server middleware.

import { initSDK, buildModule, middlewareModule } from "@vue-storefront/sdk";
import { Endpoints as BigcommerceEndpoints } from "@vsf-enterprise/bigcommerce-api";
import { bigcommerceModule } from "@vsf-enterprise/bigcommerce-sdk";
const sdkConfig = {
  bigcommerce: buildModule(middlewareModule<BigcommerceEndpoints>, {
    apiUrl: "http://localhost:8181/bigcommerce"
  }),
};

export const sdk = initSDK(sdkConfig);

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