Catalyst + B2B Buyer Portal

The steps in this guide enable Catalyst with the B2B Edition Buyer Portal, which is a traditional client-side rendered React application. The steps below also document the process for running the Open Source Buyer Portal locally, so that you can customize the experience inside of the Buyer Portal if required.

This implementation primarily handles authentication with the B2B Storefront API and triggering the render of the Buyer Portal on top of Catalyst. It is similar to the experience currently available for BigCommerce’s Stencil storefront framework.

If you are looking to integrate directly into Catalyst’s routes and components, this can be done by integrating B2B Edition’s APIs(/b2b-edition/apis).

Prerequisites

See B2B Buyer Portal Setup Overview for general prerequisites. You will need a V3 BigCommerce API token with the B2B Edition scope.

See Local Development for Catalyst prerequisites.

In addition, you will need:

• Multi-storefront enabled in the BigCommerce store and in B2B Edition

Creating the Project

Create and Configure the Storefront Channel

1. If you have not yet created a Catalyst storefront channel, create one as described in Getting Started.

2. In the B2B Edition dashboard, navigate to Storefronts and click the ellipsis (…) next to your Catalyst Headless Storefront Channel. Click “Enable B2B” and ensure the channel updates to “B2B Enabled.”
   

3. Also in the Storefronts section of the dashboard, navigate to “Edit settings” for the storefront, select “Buyer portal” settings, and set “Buyer portal type” to “Custom.”
   
   
   

4. In the store control panel, navigate to Channels and select your Catalyst storefront channel. In the “Script manager” panel, delete the “B2BEdition Footer Script” and “B2BEdition Header Script.”
   

Install Catalyst Locally

Creating a B2B-enabled Catalyst storefront follows the CLI workflow described in Manual Installation but requires setting up from a unique upstream branch and a few extra steps.

1. Run the Catalyst CLI installer with the appropriate gh-ref for including B2B:

pnpm create @bigcommerce/catalyst@latest --gh-ref @bigcommerce/catalyst-b2b-makeswift@latest

2. Supply a name for the project and respond to the interactive prompts to connect to your previously created storefront.
3. Add the following variables to .env.local:

4. Run the following from the project root to start the local server:

pnpm run dev

5. Follow the standard steps to add a remote Git repository and push your project.

Forking and Running the Buyer Portal

By default, Catalyst is integrated with the hosted version of the B2B Buyer Portal.

For developing and deploying your own custom Buyer Portal, Catalyst has built-in support for the loader scripts described in the Headless Guide  in the B2B Buyer Portal repository, which can be activated by the use of environment variables.

Catalyst and the Buyer Portal are separate applications, each with their own source control.

Clone and Run the Buyer Portal

1. Clone the B2B Buyer Portal  repository.
2. Install dependencies:

yarn install

3. Copy apps/storefront/.env-example as apps/storefront/.env. Note that, for initial development in the local environment, no values need to be changed in this file.
4. Start the development server:

yarn dev

While the development server is running, the necessary Buyer Portal loader files will be served via a local URL (usually localhost:3001). You should not browse directly to this URL; the next step will take care of updating your storefront to point to this local server.

Update Catalyst

The local Catalyst project must be configured to load the custom Buyer Portal instead of the hosted version.

In the Catalyst project:

1. Set the following variable in .env.local with the appropriate port where the Buyer Portal is running.

   LOCAL_BUYER_PORTAL_HOST=http://localhost:3001

2. Restart the Catalyst dev server.

The Buyer Portal experience in your local Catalyst storefront will now automatically reflect any customizations you make in your Buyer Portal project.

Deploying with a Custom Buyer Portal

Once you are ready to take your custom Buyer Portal to your production storefront, the Buyer Portal files must be built and deployed.

While the Buyer Portal static files can be deployed with a CDN or via your BigCommerce store’s WebDAV, the steps in this guide will assume you are deploying these build files with the Catalyst storefront itself.

For the following steps, you must know in advance the URL where your build files will be deployed. (For example, https://my-catalyst-store.com/b2b/20260101/.)

Catalyst Project Setup

The steps in this section only need to be followed once in your Catalyst project. These steps enable a “custom production” loader for the Buyer Portal and exclude any URLs beginning with /b2b/ from Next.js middleware.

1. Modify core/middleware.ts to exclude /b2b/ URLs from middleware by adding to the regular expression in config.matcher. For example:

   export const config = {
     matcher: [
       '/((?!b2b/.*|api|admin|_next/static|_next/image|_vercel|favicon.ico|xmlsitemap.php|sitemap.xml|robots.txt).*)',
     ],
   };

2. Add a new loader file at core/b2b/script-production-custom.tsx with the following contents:

'use client';
 
import Script from 'next/script';
 
import { useB2BAuth } from './use-b2b-auth';
import { useB2BCart } from './use-b2b-cart';
 
/**
 * Use these vars if using build hashes in B2B Buyer Portal files.
 */
const hashIndex = null;
const hashIndexLegacy = null;
const hashPolyfills = null;
 
interface Props {
  storeHash: string;
  channelId: string;
  token?: string;
  cartId?: string | null;
  prodUrl: string;
}
 
export function ScriptProductionCustom({
  cartId,
  storeHash,
  channelId,
  token,
  prodUrl,
}: Props) {
  useB2BAuth(token);
  useB2BCart(cartId);
 
  return (
    <>
      <Script>
        {
        window.b3CheckoutConfig = {
          routes: {
            dashboard: '/#/dashboard',
          },
        }
        window.B3 = {
          setting: {
            store_hash: '${storeHash}',
            channel_id: ${channelId},
          },
        }
        }
      </Script>
      <Script
        type="module"
        crossOrigin=""
        src={`${prodUrl}/index${hashIndex ? `.${hashIndex}` : ''}.js`}
      ></Script>
      <Script
        noModule
        crossOrigin=""
        src={`${prodUrl}/polyfills-legacy${hashPolyfills ? `.${hashPolyfills}` : ''}.js`}
      ></Script>
      <Script
        noModule
        crossOrigin=""
        src={`${prodUrl}/index-legacy${hashIndexLegacy ? `.${hashIndexLegacy}` : ''}.js`}
      ></Script>
    </>
  );
}

3. In core/b2b/loader.tsx, add the import of ScriptProductionCustom and update EnvironmentSchema and the constants at the beginning of B2BLoader as shown.

...
import { ScriptProductionCustom } from './script-production-custom';
 
const EnvironmentSchema = z.object({
  ...
  LOCAL_BUYER_PORTAL_HOST: z.string().url().optional(),
  PROD_BUYER_PORTAL_BASE_URL: z.string().url().optional(),
  STAGING_B2B_CDN_ORIGIN: z.string().optional(),
});
 
export async function B2BLoader() {
  const {
    ...
    LOCAL_BUYER_PORTAL_HOST,
    PROD_BUYER_PORTAL_BASE_URL,
    STAGING_B2B_CDN_ORIGIN,
  } = EnvironmentSchema.parse(process.env);
 
  ...  
}

4. Also in core/b2b/loader.tsx, add a new conditional block after the one for LOCAL_BUYER_PORTAL_HOST, as shown below:

export async function B2BLoader() {
  ...
 
  if (LOCAL_BUYER_PORTAL_HOST) {
    ...
  }
    
  if (PROD_BUYER_PORTAL_BASE_URL) {
    return (
      <ScriptProductionCustom
        cartId={session?.user?.cartId}
        channelId={BIGCOMMERCE_CHANNEL_ID}
        storeHash={BIGCOMMERCE_STORE_HASH}
        token={session?.b2bToken}
        prodUrl={PROD_BUYER_PORTAL_BASE_URL}
      />
    );
  }
 
  ...
}

With these modifications in place, the Buyer Portal files injected into your Catalyst storefront will be loaded from the URL set in PROD_BUYER_PORTAL_BASE_URL, if it exists.

In the Buyer Portal Project

The remaining steps apply whenever new changes to your custom Buyer Portal are to be published.

1. Set values in .env appropriately for building.

2. Run the build.

yarn build

In the Catalyst Project

1. Copy the contents of apps/storefront/dist from the Buyer Portal project into a date-based subdirectory like core/public/b2b/20260101.

2. Deploy the Catalyst project.

As an example for how the URLs of the final build files should be represented, consider that the Buyer Portal dist directory should contain these two files/subdirectories (among others):
assets
index.js

After copying into the public subdirectory shown above and deploying Catalyst, we should have URLs like:
https://my-catalyst-store.com/b2b/20260101/assets
https://my-catalyst-store.com/b2b/20260101/index.js

Loading the Deployed Buyer Portal

In the local Catalyst project, take the following steps in .env.local to test with the deployed Buyer Portal:

1. Comment out LOCAL_BUYER_PORTAL_HOST.

2. Add PROD_BUYER_PORTAL_BASE_URL with the base URL of the Buyer Portal build files. For example:

   PROD_BUYER_PORTAL_BASE_URL=https://my-catalyst-store.com/b2b/20260101

When you’re ready to activate your new Buyer Portal deployment in production, set the same PROD_BUYER_PORTAL_BASE_URL environment variable in your Catalyst hosting environment and re-deploy.