From c0733f67ba02fca8fd13dd1ce595ab0d4a9e4fc7 Mon Sep 17 00:00:00 2001 From: Terra Hyde Date: Wed, 1 Oct 2025 10:09:22 -0600 Subject: [PATCH 1/4] Initial branch creation with relevant guide files. Base information added to each file. Guides for Headless and Stencil filled in. Missing screenshots. Other files are placeholders for future content. --- .../docs/buyer-portal/catalyst.mdx | 13 ++ .../docs/buyer-portal/headless.mdx | 161 ++++++++++++++++++ .../docs/buyer-portal/overview.mdx | 29 ++++ .../b2b-edition/docs/buyer-portal/stencil.mdx | 130 ++++++++++++++ 4 files changed, 333 insertions(+) create mode 100644 docs/b2b-edition/docs/buyer-portal/catalyst.mdx create mode 100644 docs/b2b-edition/docs/buyer-portal/headless.mdx create mode 100644 docs/b2b-edition/docs/buyer-portal/overview.mdx create mode 100644 docs/b2b-edition/docs/buyer-portal/stencil.mdx diff --git a/docs/b2b-edition/docs/buyer-portal/catalyst.mdx b/docs/b2b-edition/docs/buyer-portal/catalyst.mdx new file mode 100644 index 000000000..365a15189 --- /dev/null +++ b/docs/b2b-edition/docs/buyer-portal/catalyst.mdx @@ -0,0 +1,13 @@ +# Catalyst Setup and Deployment + +## Default State \- Custom Buyer Portal + +## Running in Development + +## Building and Deploying + +### Versioning Strategy? + +## Pulling Upstream Changes + +## Using the Hosted Buyer Portal \ No newline at end of file diff --git a/docs/b2b-edition/docs/buyer-portal/headless.mdx b/docs/b2b-edition/docs/buyer-portal/headless.mdx new file mode 100644 index 000000000..c79948406 --- /dev/null +++ b/docs/b2b-edition/docs/buyer-portal/headless.mdx @@ -0,0 +1,161 @@ +# Custom Headless Setup and Deployment + +## Adding the Hosted Buyer Portal + +TODO: Is this even a documented/supported path? + +## Forking and Running the Buyer Portal + +### Prerequisites + +* Node.js: + * We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage your Node installation. +* Yarn package manager + * Install globally with `npm i -g yarn` + +See the [B2B Buyer Portal README](https://github.com/bigcommerce/b2b-buyer-portal) for the current minimum required version of Node and Yarn. + +### Clone and Run the Buyer Portal + +1. Clone the [B2B Buyer Portal](https://github.com/bigcommerce/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 Your Storefront Code + +With your local Buyer Portal instance running, you must now inject the appropriate scripts to load the Buyer Portal in your storefront application. + +See the [Headless Guide](https://github.com/bigcommerce/b2b-buyer-portal/blob/main/docs/headless.md) in the B2B Buyer Portal repository for details on the scripts to include in `` and at the end of ``. + +It is always recommended to explicitly configure your B2B Edition settings to account for a customized Buyer Portal. Navigate to B2B Edition in the control panel and set “Buyer Portal type” to “Custom.” + +* In a single storefront configuration, this is found in the main Buyer Portal settings. + + ![]() {/* @TODO: Add screenshot */} + +* In a multi-storefront configuration, update this setting for the specific storefront. + + ![]() {/* @TODO: Add screenshot */} + +## Building and Deploying + +Once you are ready to take your custom Buyer Portal to your production storefront, the Buyer Portal files must be built and deployed. + +For the following steps, you must know in advance the URL where your build files will be deployed. (For example, `https://my.custom.cdn/generated/b2b`/.) + +1. Set values in `.env` appropriately for building. + +| Var | Value | +| :---- | :---- | +| `VITE_IS_LOCAL_ENVIRONMENT` | `FALSE` | +| `VITE_ASSETS_ABSOLUTE_PATH` | The absolute URL where the build files will be deployed. For example, if the build files from `dist` will be uploaded to the URL `https://my.custom/cdn/generated/b2b`/, this should be provided as the value. Make sure to include the trailing slash. | +| `VITE_DISABLE_BUILD_HASH` | By default, build files will include a hash to invalidate previous caches. (For example, `index-{hash}.js`) Set this value to `TRUE` if you want to build files without the hash. (For example, `index.js`) This is appropriate if you are using a folder-based naming scheme for cache busting instead of file-based. | + +2. Run the build. + +`yarn build` + +3. Copy the contents of `apps/storefront/dist` to your chosen CDN or hosting provider. + + As an example for how the URLs of the final build files should be represented, consider that `dist` should contain these two files/directories (among others): + * `assets` + * `index.js (or index-{hash}.js)` + + Assuming the example URL value above was used for `VITE_ASSETS_ABSOLUTE_PATH`, after deployment we should have URLs like: + * `https://my.custom/cdn/generated/b2b/assets` + * `https://my.custom/cdn/generated/b2b/index.js` + +4. Update the scripts in your storefront code to load the deployed loader files, as detailed in the [Headless Guide](https://github.com/bigcommerce/b2b-buyer-portal/blob/main/docs/headless.md#deploying-the-project) in the Buyer Portal repo. + + +When re-building and re-deploying your custom Buyer Portal, you should clear the local contents of `.turbo/cache` before running `yarn build` to ensure that all updated code is reflected in the build. Also make sure to update your scripts in Script Manager again after deploying your new build files. + + +### Deploying with WebDAV + +Your BigCommerce store’s [WebDAV storage](https://support.bigcommerce.com/s/article/File-Access-WebDAV) can be a viable option for serving your custom B2B Buyer Portal files without sourcing a third-party CDN. + +Follow the instructions in the above support article to learn about enabling WebDAV and connecting with a client like Cyberduck. Once you’re connected, you can use your store’s WebDAV as the upload destination for the steps described in Building and Deploying. + +The directory `content` should be used for static files of this nature. Let’s say you intend to upload the build files from `dist` into `content/b2b` on your store’s WebDAV. This will make your Buyer Portal files available at the following URL: + +`https://{my-store}.com/content/b2b/` + +The files can also be accessed via the store’s canonical URL, in this format: + +`https://store-{store-hash}.mybigcommerce.com/content/b2b/` + +Either of these should be used as the value of `VITE_ASSETS_ABSOLUTE_PATH` before running `yarn build`, and the same value should be utilized when updating the scripts in Script Manager. + +### Deploying with Your Storefront + +In a headless storefront scenario, you’re already deploying a custom frontend web application, and so you have the opportunity to deploy Buyer Portal build files with your own storefront rather than with a third-party CDN or your store’s WebDAV. + +As an example, let’s say your storefront is a Next.js application and served from `mystore.com`. You might decide that the Buyer Portal static files will be available at `https://mystore.com/assets/b2b/`. + +Your first step, as always, would be to set this base URL as the value of `VITE_ASSETS_ABSOLUTE_PATH` in your Buyer Portal codebase before building. + +In Next.js, any static files in the `public` project subdirectory will be served directly from the base URL. Therefore, to complete your deployment after building the Buyer Portal files, sync the contents of `dist` into `public/assets/b2b` within your Next.js project, update your loader scripts, and re-deploy your storefront. + +### Versioning and Toggle Strategy + +As mentioned above, by default the build process includes a hash in the filename of several key files. If you’re hosting your Buyer Portal build files with your headless storefront, for example, the following would be an example of the final URL of such a file: + +`https://mystore.com/assets/b2b/index-{hash}.js` + +This is a file-based strategy for avoiding stale cached files being served to shoppers. Upon a new build/deploy, you *must* make sure to update each file URL referenced in your loader scripts each time you deploy new Buyer Portal build files. + +Another strategy is to include a unique identifier in the *subdirectory* of your deployed location rather than in each individual filename. For example, say you configure `VITE_DISABLE_BUILD_HASH` to `TRUE` before building (resulting in filenames without a hash) and then upload the build files to a subdirectory in your storefront project that includes a date-based string. This could result in URLs like the following: + +`https://mystore.com/assets/b2b-20260101/index.js` + +As with the file-based strategy, your loader scripts must be updated to reflect this new path. However, this approach can make it easier to upload your new build files without overwriting previous build files, ensuring that the previous Buyer Portal version continues to be served to end users until your loader scripts are updated. + +In a headless storefront, it’s usually easy to incorporate the build hash or date-based string into an environment variable and avoid the need to update your actual loader scripts for new build files. For example, if you’re using the file hash approach, you might create an environment variable like the following in your storefront application: + +`B2B_BUILD_HASH={hash}` + +In Next.js, your `` loader script component can incorporate this environment var as follows: + +```html copy filename="Build hash environment variable" +const { B2B_BUILD_HASH } = process.env; +... + +``` + +With this technique in place, subsequent builds of your custom Buyer Portal won’t require you to change your storefront code, only update your variable in the appropriate environment and redeploy. + +You may find it useful to implement a similar strategy to toggle your storefront loader scripts when you are actively developing on the Buyer Portal, without the need for changing the script code each time. For example (again, in your storefront application, not the Buyer Portal project), create the following environment variable: + +`B2B_LOCAL_LOADER=TRUE` + +The following example Next.js code can toggle the appropriate loader scripts based on whether you’re running a local Buyer Portal project or loading a deployed Buyer Portal. + +`const { B2B_LOCAL_LOADER } = process.env;` +`if (B2B_LOCAL_LOADER) {` + `// ... Local Buyer Portal script` +`} else {` + `// ... Deployed Buyer Portal script` +`}` + +## Co-Locating the Buyer Portal with Your Storefront Code + +While your headless storefront and the Buyer Portal are, by nature, separate applications with their own codebases, you may find it desirable to locate their source code together in the same repository. + +Managing code together in this way might offer benefits like: + +* Consistent deployment of Buyer Portal customizations and related storefront customizations +* Automation of copying Buyer Portal build files into a final deployment directory +* Orchestration of related tasks, such as running the local servers for both the storefront application and Buyer Portal \ No newline at end of file diff --git a/docs/b2b-edition/docs/buyer-portal/overview.mdx b/docs/b2b-edition/docs/buyer-portal/overview.mdx new file mode 100644 index 000000000..d95ac8392 --- /dev/null +++ b/docs/b2b-edition/docs/buyer-portal/overview.mdx @@ -0,0 +1,29 @@ +# B2B Buyer Portal Setup and Deployment + +## Intro ... + +* Stencil Setup Guide (link) +* Catalyst Setup Guide (link) +* Custom Headless Setup Guide (link) + +## Prerequisites + +## Buyer Portal Concepts + +### The Buyer Portal React Application + +* Tech stack +* B2B GraphQL API + +Two options: + +* Hosted Buyer Portal +* Custom Buyer Portal + +### Customizing and Hosting the Buyer Portal + +* Running it locally +* Building and deploying +* Script config + +### Theming Without a Custom Buyer Portal \ No newline at end of file diff --git a/docs/b2b-edition/docs/buyer-portal/stencil.mdx b/docs/b2b-edition/docs/buyer-portal/stencil.mdx new file mode 100644 index 000000000..576eddef9 --- /dev/null +++ b/docs/b2b-edition/docs/buyer-portal/stencil.mdx @@ -0,0 +1,130 @@ +# Stencil Setup and Deployment + +## Default State — Hosted Buyer Portal + +Any Stencil storefront with B2B Edition enabled will include the hosted version of the B2B Buyer Portal by default. + +When B2B Edition is activated for the storefront, B2BEdition Header Script and B2BEdition Footer Script will automatically be configured in the channel’s Script Manager. + +![]() {/* @TODO: add screenshot */} + +## The Role of Script Manager + +Scripts configured within Script Manager for a storefront channel are automatically injected into the Stencil theme for that storefront. In the case of the B2B Buyer Portal, these scripts are injected into all pages of the storefront to initialize the React application. + +This means that, in Stencil, this entry point is the traffic controller that determines whether the storefront loads the hosted Buyer Portal experience or your own customized Buyer Portal. + +With the default scripts in place loading the hosted Buyer Portal, your storefront will automatically receive updates when new versions of the Buyer Portal are released. However, if you have customized the Buyer Portal as described below, it is up to you to pull in upstream changes from the Buyer Portal repository and integrate them with your own customizations. + +## Forking and Running the Buyer Portal + +### Prerequisites + +* Node.js: + * We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage your Node installation. +* Yarn package manager + * Install globally with `npm i -g yarn` + +See the [B2B Buyer Portal README](https://github.com/bigcommerce/b2b-buyer-portal) for the current minimum required version of Node and Yarn. + +### Clone and Run the Buyer Portal + +1. Clone the [B2B Buyer Portal](https://github.com/bigcommerce/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 Stencil storefront to point to this local server. + +### Update the Storefront + +After your local Buyer Portal instance is running, you must now update your Stencil storefront to inject this version of the Buyer Portal instead of the default hosted version. + +1. Navigate to Script Manager in the BigCommerce control panel. (In a multi-storefront configuration, you’ll find this in the settings for the individual storefront channel.) +2. Delete the default “B2BEdition Header Script” and “B2BEdition Footer Script.” +3. Add two new entries for header and footer scripts as described in the [Stencil Guide](https://github.com/bigcommerce/b2b-buyer-portal/blob/main/docs/stencil.md) in the Buyer Portal repository. +4. Navigate to B2B Edition in the control panel and set “Buyer Portal type” to “Custom.” + 1. In a single storefront configuration, this is found in the main Buyer Portal settings. + + ![]() {/* @TODO: add screenshot */} + + 2. In a multi-storefront configuration, update this setting for the specific storefront. + + ![]() {/* @TODO: add screenshot */} + +Using this “Custom” setting in B2B Edition will ensure that automatic updates will not interfere with the scripts you have configured to inject your custom Buyer Portal. + +With your local Buyer Portal instance running and the storefront scripts updated, your custom Buyer Portal will be loaded into the Stencil storefront, and you can actively develop on the Buyer Portal code. + + +Note that Script Manager will control the Buyer Portal injected into the storefront whether in a Stencil CLI live preview or in the actual hosted storefront. The above steps should only be taken in a sandbox store or on a storefront channel in prelaunch status. + + +## Building and Deploying + +Once you are ready to take your custom Buyer Portal to your production storefront, the Buyer Portal files must be built and deployed. + +For the following steps, you must know in advance the URL where your build files will be deployed. (For example, `https://my.custom.cdn/generated/b2b`/.) + +1. Set values in `.env` appropriately for building. + +| Var | Value | +| :---- | :---- | +| `VITE_IS_LOCAL_ENVIRONMENT` | `FALSE` | +| `VITE_ASSETS_ABSOLUTE_PATH` | The absolute URL where the build files will be deployed. For example, if the build files from `dist` will be uploaded to the URL `https://my.custom/cdn/generated/b2b`/, this should be provided as the value. Make sure to include the trailing slash. | +| `VITE_DISABLE_BUILD_HASH` | By default, build files will include a hash to invalidate previous caches. (For example, `index-{hash}.js`) Set this value to `TRUE` if you want to build files without the hash. (For example, `index.js`) This is appropriate if you are using a folder-based naming scheme for cache busting instead of file-based. | + +2. Run the build. + +`yarn build` + +3. Copy the contents of `apps/storefront/dist` to your chosen CDN or hosting provider. + + As an example for how the URLs of the final build files should be represented, consider that `dist` should contain these two files/directories (among others): + * `assets` + * `index.js (or index-{hash}.js)` + + Assuming the example URL value above was used for `VITE_ASSETS_ABSOLUTE_PATH`, after deployment we should have URLs like: + * `https://my.custom/cdn/generated/b2b/assets` + * `https://my.custom/cdn/generated/b2b/index.js` + +4. Navigate to Script Manager in the BigCommerce control panel and update the B2B Edition header and footer scripts as described in the [Stencil Guide](https://github.com/bigcommerce/b2b-buyer-portal/blob/main/docs/stencil.md#deploying-the-project) in the Buyer Portal repository, making sure once again to use the appropriate base URL. + + +*When re-building and re-deploying your custom Buyer Portal, you should clear the local contents of `.turbo/cache` before running `yarn build` to ensure that all updated code is reflected in the build. Also make sure to update your scripts in Script Manager again after deploying your new build files.* + + +### Deploying with WebDAV + +Your BigCommerce store’s [WebDAV storage](https://support.bigcommerce.com/s/article/File-Access-WebDAV) can be a viable option for serving your custom B2B Buyer Portal files without sourcing a third-party CDN. + +Follow the instructions in the above support article to learn about enabling WebDAV and connecting with a client like Cyberduck. Once you’re connected, you can use your store’s WebDAV as the upload destination for the steps described in Building and Deploying. + +The directory `content` should be used for static files of this nature. Let’s say you intend to upload the build files from `dist` into `content/b2b` on your store’s WebDAV. This will make your Buyer Portal files available at the following URL: + +`https://{my-store}.com/content/b2b/` + +The files can also be accessed via the store’s canonical URL, in this format: + +`https://store-{store-hash}.mybigcommerce.com/content/b2b/` + +Either of these should be used as the value of `VITE_ASSETS_ABSOLUTE_PATH` before running `yarn build`, and the same value should be utilized when updating the scripts in Script Manager. + +### Versioning Strategy + +As mentioned above, by default the build process includes a hash in the filename of several key files. If you’re hosting your build files on your store’s WebDAV, for example, the following would be an example of the final URL of such a file: + +`https://{my-store}.com/content/b2b/index-{hash}.js` + +This is a file-based strategy for avoiding stale cached files being served to shoppers. Upon a new build/deploy, you *must* make sure to update each file URL referenced in Script Manager each time you deploy new Buyer Portal build files. + +Another strategy is to include a unique identifier in the *subdirectory* of your deployed location rather than in each individual filename. For example, say you configure `VITE_DISABLE_BUILD_HASH` to `TRUE` before building (resulting in filenames without a hash) and then upload the build files to a subdirectory of your store’s WebDAV that includes a date-based string. This could result in URLs like the following: + +`https://{my-store}.com/content/b2b-20260101/index.js` + +As with the file-based strategy, your scripts in Script Manager must be updated to reflect this new path. However, this approach can make it easier to upload your new build files without overwriting previous build files, ensuring that the previous Buyer Portal version continues to be served to end users until Script Manger is updated. \ No newline at end of file From b9253f424a5f68760f206a556eeb8146f0ad9fbd Mon Sep 17 00:00:00 2001 From: Terra Hyde Date: Fri, 10 Oct 2025 10:08:05 -0600 Subject: [PATCH 2/4] Updated Overview and Catalyst docs --- .../docs/buyer-portal/catalyst.mdx | 171 +++++++++++++++++- .../docs/buyer-portal/overview.mdx | 69 +++++-- 2 files changed, 218 insertions(+), 22 deletions(-) diff --git a/docs/b2b-edition/docs/buyer-portal/catalyst.mdx b/docs/b2b-edition/docs/buyer-portal/catalyst.mdx index 365a15189..6419e2533 100644 --- a/docs/b2b-edition/docs/buyer-portal/catalyst.mdx +++ b/docs/b2b-edition/docs/buyer-portal/catalyst.mdx @@ -1,13 +1,170 @@ -# Catalyst Setup and Deployment +# Catalyst \+ B2B Buyer Portal -## Default State \- Custom Buyer Portal + +**EXPERIMENTAL: The integration of BigCommerce B2B Edition with Catalyst is experimental and subject to change. It is advisable to work with BigCommerce professional services in order to implement this integration.** + -## Running in Development +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. -## Building and Deploying +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. -### Versioning Strategy? +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). -## Pulling Upstream Changes + +Using the default B2B Edition implementation with Catalyst requires support for Customer Access Tokens (CAT). All new B2B Edition stores support this functionality by default. If your store had B2B Edition prior to July 2025, you must contact support to enable this feature. + -## Using the Hosted Buyer Portal \ No newline at end of file +## Prerequisites + +See [B2B Buyer Portal Setup Overview](/b2b-edition/docs/buyer-portal) for general prerequisites. You will need a V3 BigCommerce API token with the B2B Edition scope. + +See [Local Development](link) 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(link). + +The initial deployed preview storefront does not support B2B Buyer Portal features. You must follow the remaining steps and deploy your storefront to your own hosting to enable the Buyer Portal. + +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.” + ![](screenshot) +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.” + ![](screenshot) +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.” + ![](screenshot) + +### Install Catalyst Locally + +Creating a B2B-enabled Catalyst storefront follows the CLI workflow described in [Manual Installation](link) 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`: + | Var | Value | + | :---- | :---- | + | `B2B_API_HOST` | `https://api-b2b.bigcommerce.com` | + | `B2B_API_TOKEN` | Your V3 token with the B2B Edition scope | +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. + +![](screenshot) + +For developing and deploying your own custom Buyer Portal, Catalyst has built-in support for the loader scripts described in the [Headless Guide](https://github.com/bigcommerce/b2b-buyer-portal/blob/main/docs/headless.md) 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](https://github.com/bigcommerce/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. + + +These steps also assume a strategy for static file cache invalidation involving a date-based subdirectory. We’ll note where the process differs if you choose to use the Buyer Portal build hashes. + + +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/.) + +### In the Buyer Portal Project + +1. Set values in `.env` appropriately for building. + | Var | Value | + | :---- | :---- | + | `VITE_IS_LOCAL_ENVIRONMENT` | `FALSE` | + | `VITE_ASSETS_ABSOLUTE_PATH` | The absolute URL where the build files will be deployed. Make sure to include the trailing slash. This guide assumes deployment in a date-based subdirectory of the Catalyst project’s `public` directory, for a URL like: `https://my-catalyst-store.com/b2b/20260101/` | + | `VITE_DISABLE_BUILD_HASH` | `TRUE` NOTE: If you wish to handle static file cache invalidation with build hashes in file names (for example, `index-{hash}.js`) instead of with a subdirectory, set this to `FALSE` instead. | +2. Run the build. + ``` + yarn build + ``` + +When re-building and re-deploying your custom Buyer Portal, if only `.env` variables have changed, you should clear the local contents of `.turbo/cache` before running `yarn build` to ensure that all updated code is reflected in the build. + + +### In the Catalyst Project + +1. Modify `core/middleware.ts` to exclude URLs beginning with `/b2b/` from middleware by adding to the regular expression in `config.matcher`. For example: + ```typescript + export const config = { + matcher: ['/((?!b2b/.*|api|admin|_next/static|_next/image|_vercel|favicon.ico|xmlsitemap.php|sitemap.xml|robots.txt).*)', + ], + }; + ``` + NOTE: This step must only be performed once, not on every new Buyer Portal deployment. +2. Copy the contents of `apps/storefront/dist` from the Buyer Portal project into a date-based subdirectory like `core/public/b2b/20260101.` +3. 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` + + +One of the advantages of using a varying subdirectory for new deployments of the Buyer Portal is that older deployments can be left in place, so that a previous Buyer Portal version will continue to be rendered until you choose to activate the new deployment with the environment configuration in the next step. This also makes reverting to a previous Buyer Portal version simple. + + + +If you’ve chosen to include build hashes in the filenames of your Buyer Portal files, you must also update the constants defining those hashes in `core/b2b/script-production-custom.tsx`. It’s likely you will also use a consistent location for the build files, like simply `core/public/b2b`, rather than a varying subdirectory. + + +### 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_HOST` with the base URL of the Buyer Portal build files. For example: + `PROD_BUYER_PORTAL_HOST=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_HOST` environment variable in your Catalyst hosting environment and re-deploy. + + +**If you’ve chosen to include build hashes in the filenames of your Buyer Portal files as a cache invalidation strategy, you will likely choose a permanent base URL for your build files and will not need to update `PROD_BUYER_PORTAL_HOST` on each new deployment.** + \ No newline at end of file diff --git a/docs/b2b-edition/docs/buyer-portal/overview.mdx b/docs/b2b-edition/docs/buyer-portal/overview.mdx index d95ac8392..f8e320e23 100644 --- a/docs/b2b-edition/docs/buyer-portal/overview.mdx +++ b/docs/b2b-edition/docs/buyer-portal/overview.mdx @@ -1,29 +1,68 @@ # B2B Buyer Portal Setup and Deployment -## Intro ... +## Intro -* Stencil Setup Guide (link) -* Catalyst Setup Guide (link) -* Custom Headless Setup Guide (link) +These guides help developers customize and deploy the BigCommerce B2B Buyer Portal across Stencil, Catalyst, and fully custom headless storefronts. The Buyer Portal is a React-based application that enables advanced B2B workflows such as account management, quote requests, and order histories. Customizing the Buyer Portal lets you deliver unique experiences, extend business logic, and control branding for your B2B buyers. + +Whether you use BigCommerce’s Stencil theme engine, the Catalyst storefront experience, or your own headless setup, these resources provide a step-by-step approach for forking, configuring, running, and deploying a custom Buyer Portal. The guides are designed for developers familiar with Node.js, React, and Yarn, and aim to get you started quickly with building and launching a tailored Buyer Portal experience. + +### Guides + +- [Stencil Setup Guide](/b2b-edition/docs/buyer-portal/stencil) +- [Catalyst Setup Guide](/docs/storefront/catalyst/experiments/b2b) +- [Custom Headless Setup Guide](/b2b-edition/docs/buyer-portal/headless) ## Prerequisites +- **Node.js** + - We recommend managing installations with [nvm](https://github.com/nvm-sh/nvm). +- **Yarn package manager** + - Install globally with `npm i -g yarn`, or enable locally using `corepack enable yarn` to ensure the correct project version. +- **Git** + - Required for cloning repositories and managing code. +- **BigCommerce store with B2B Edition enabled** + - Needed for configuring and deploying the Buyer Portal. +- **React and JavaScript/TypeScript experience** +- **V3 BigCommerce API token with B2B Edition scope** (for advanced integrations) + +See the [B2B Buyer Portal README](https://github.com/bigcommerce/b2b-buyer-portal) for the current minimum required versions of Node and Yarn. + ## Buyer Portal Concepts -### The Buyer Portal React Application +### What is the Buyer Portal? + +The Buyer Portal is a React application providing B2B buyers a dedicated interface for business-specific workflows in BigCommerce. It connects to the B2B GraphQL API and supports two main configurations: + +- **Hosted Buyer Portal:** Managed by BigCommerce, updated automatically. +- **Custom Buyer Portal:** Forked and customized by merchants/agencies for advanced branding, features, or integrations. + +### Why Customize the Buyer Portal? + +Customizing the Buyer Portal lets you: +- Tailor UI/UX and workflows for your buyers. +- Integrate with your own business logic or third-party platforms. +- Control release cycles and updates. +- Support multi-storefront and multiple deployment strategies. + +### Customizing the Hosted Buyer Portal -* Tech stack -* B2B GraphQL API +The Hosted Buyer Portal is the default B2B buyer experience managed and automatically updated by BigCommerce. It provides a robust set of built-in customization options directly within the B2B Edition control panel, allowing you to tailor the portal to your brand and business needs with limited code requirements. -Two options: +Customizable features include: +- **Branding:** Upload your company logo, set primary and accent colors to match your storefront’s design, and adjust other visual elements. +- **Feature Toggles:** Enable or disable specific Buyer Portal features such as Quotes, Order History, or Account Management depending on your business requirements. +- **Layout and Display Settings:** Configure portal layout preferences, including navigation, page visibility, or content blocks, to optimize the buyer experience. +- **Localization:** Set language and currency preferences to support international buyers. +- **Account Controls:** Manage buyer access, permissions, and visibility of features on an account-by-account basis. -* Hosted Buyer Portal -* Custom Buyer Portal +These settings are accessible through the B2B Edition area of your BigCommerce control panel. Any changes made here are applied instantly and are supported by BigCommerce, with ongoing updates and enhancements provided automatically. -### Customizing and Hosting the Buyer Portal +For more information on customizing the Hosted Buyer Portal, see [B2B Edition Settings (Help Center)](https://support.bigcommerce.com/s/article/B2B-Edition-Settings). -* Running it locally -* Building and deploying -* Script config +If you want more advanced control or integration than the built-in options allow, consider switching to a custom Buyer Portal. However, for most merchants, the Hosted Buyer Portal’s built-in controls offer a fast, reliable, and supported way to create a branded B2B buyer experience. -### Theming Without a Custom Buyer Portal \ No newline at end of file +## Resources +- **[B2B Edition Settings (Help Center)](https://support.bigcommerce.com/s/article/B2B-Edition-Settings)** +- **[B2B Buyer Portal GitHub Repository](https://github.com/bigcommerce/b2b-buyer-portal)** Source code, README, and documentation for the Buyer Portal project. +- **[Catalyst Overview](https://support.bigcommerce.com/s/article/Catalyst)** +- **[BigCommerce WebDAV Support](https://support.bigcommerce.com/s/article/File-Access-WebDAV)** From a1bd90338b543dc69332ad2a00e7ca2fb2622519 Mon Sep 17 00:00:00 2001 From: Terra Hyde Date: Fri, 10 Oct 2025 10:35:29 -0600 Subject: [PATCH 3/4] Updated dead links. Left placeholders for images. --- .../docs/buyer-portal/catalyst.mdx | 19 +++++++++---------- .../docs/buyer-portal/headless.mdx | 18 +++++++----------- .../b2b-edition/docs/buyer-portal/stencil.mdx | 9 ++------- 3 files changed, 18 insertions(+), 28 deletions(-) diff --git a/docs/b2b-edition/docs/buyer-portal/catalyst.mdx b/docs/b2b-edition/docs/buyer-portal/catalyst.mdx index 6419e2533..f589396e7 100644 --- a/docs/b2b-edition/docs/buyer-portal/catalyst.mdx +++ b/docs/b2b-edition/docs/buyer-portal/catalyst.mdx @@ -16,9 +16,9 @@ Using the default B2B Edition implementation with Catalyst requires support for ## Prerequisites -See [B2B Buyer Portal Setup Overview](/b2b-edition/docs/buyer-portal) for general prerequisites. You will need a V3 BigCommerce API token with the B2B Edition scope. +See [B2B Buyer Portal Setup Overview](/b2b-edition/docs/buyer-portal#prerequisites) for general prerequisites. You will need a V3 BigCommerce API token with the B2B Edition scope. -See [Local Development](link) for Catalyst prerequisites. +See [Local Development](/docs/storefront/catalyst/getting-started/local-development#prerequisites) for Catalyst prerequisites. In addition, you will need: @@ -28,20 +28,20 @@ In addition, you will need: ### Create and Configure the Storefront Channel -1. If you have not yet created a Catalyst storefront channel, create one as described in Getting Started(link). +1. If you have not yet created a Catalyst storefront channel, create one as described in [Getting Started](/docs/storefront/catalyst/getting-started). The initial deployed preview storefront does not support B2B Buyer Portal features. You must follow the remaining steps and deploy your storefront to your own hosting to enable the Buyer Portal. 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.” - ![](screenshot) + ![]() {/* @TODO: add screenshot */} 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.” - ![](screenshot) + ![]() {/* @TODO: add screenshot */} 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.” - ![](screenshot) + ![]() {/* @TODO: add screenshot */} ### Install Catalyst Locally -Creating a B2B-enabled Catalyst storefront follows the CLI workflow described in [Manual Installation](link) but requires setting up from a unique upstream branch and a few extra steps. +Creating a B2B-enabled Catalyst storefront follows the CLI workflow described in [Manual Installation](/docs/storefront/catalyst/development/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: ``` @@ -63,7 +63,7 @@ Creating a B2B-enabled Catalyst storefront follows the CLI workflow described in By default, Catalyst is integrated with the hosted version of the B2B Buyer Portal. -![](screenshot) +![]() {/* @TODO: add screenshot */} For developing and deploying your own custom Buyer Portal, Catalyst has built-in support for the loader scripts described in the [Headless Guide](https://github.com/bigcommerce/b2b-buyer-portal/blob/main/docs/headless.md) in the B2B Buyer Portal repository, which can be activated by the use of environment variables. @@ -90,8 +90,7 @@ The local Catalyst project must be configured to load the custom Buyer Portal in In the Catalyst project: -1. Set the following variable in `.env.local` with the appropriate port where the Buyer Portal is running. - +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. diff --git a/docs/b2b-edition/docs/buyer-portal/headless.mdx b/docs/b2b-edition/docs/buyer-portal/headless.mdx index c79948406..f5c0a2e36 100644 --- a/docs/b2b-edition/docs/buyer-portal/headless.mdx +++ b/docs/b2b-edition/docs/buyer-portal/headless.mdx @@ -8,24 +8,20 @@ TODO: Is this even a documented/supported path? ### Prerequisites -* Node.js: - * We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage your Node installation. -* Yarn package manager - * Install globally with `npm i -g yarn` - -See the [B2B Buyer Portal README](https://github.com/bigcommerce/b2b-buyer-portal) for the current minimum required version of Node and Yarn. +See [B2B Buyer Portal Setup Overview](/b2b-edition/docs/buyer-portal#prerequisites) for general prerequisites. You will need a V3 BigCommerce API token with the B2B Edition scope. ### Clone and Run the Buyer Portal 1. Clone the [B2B Buyer Portal](https://github.com/bigcommerce/b2b-buyer-portal) repository. 2. Install dependencies: - -`yarn install` - + ``` + 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` + ``` + 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. diff --git a/docs/b2b-edition/docs/buyer-portal/stencil.mdx b/docs/b2b-edition/docs/buyer-portal/stencil.mdx index 576eddef9..25a544f77 100644 --- a/docs/b2b-edition/docs/buyer-portal/stencil.mdx +++ b/docs/b2b-edition/docs/buyer-portal/stencil.mdx @@ -20,12 +20,7 @@ With the default scripts in place loading the hosted Buyer Portal, your storefro ### Prerequisites -* Node.js: - * We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage your Node installation. -* Yarn package manager - * Install globally with `npm i -g yarn` - -See the [B2B Buyer Portal README](https://github.com/bigcommerce/b2b-buyer-portal) for the current minimum required version of Node and Yarn. +See [B2B Buyer Portal Setup Overview](/b2b-edition/docs/buyer-portal#prerequisites) for general prerequisites. You will need a V3 BigCommerce API token with the B2B Edition scope. ### Clone and Run the Buyer Portal @@ -127,4 +122,4 @@ Another strategy is to include a unique identifier in the *subdirectory* of your `https://{my-store}.com/content/b2b-20260101/index.js` -As with the file-based strategy, your scripts in Script Manager must be updated to reflect this new path. However, this approach can make it easier to upload your new build files without overwriting previous build files, ensuring that the previous Buyer Portal version continues to be served to end users until Script Manger is updated. \ No newline at end of file +As with the file-based strategy, your scripts in Script Manager must be updated to reflect this new path. However, this approach can make it easier to upload your new build files without overwriting previous build files, ensuring that the previous Buyer Portal version continues to be served to end users until Script Manger is updated. From df719432828440d4db9c949f529c68a8550da8b0 Mon Sep 17 00:00:00 2001 From: Terra Hyde Date: Fri, 10 Oct 2025 10:43:55 -0600 Subject: [PATCH 4/4] Moved catalyst guide into Catalyst section under Experiments and deleted outdated B2B guide. --- docs/storefront/catalyst/development/b2b.mdx | 170 ------------------ .../catalyst/experiments/buyer-portal.mdx} | 0 2 files changed, 170 deletions(-) delete mode 100644 docs/storefront/catalyst/development/b2b.mdx rename docs/{b2b-edition/docs/buyer-portal/catalyst.mdx => storefront/catalyst/experiments/buyer-portal.mdx} (100%) diff --git a/docs/storefront/catalyst/development/b2b.mdx b/docs/storefront/catalyst/development/b2b.mdx deleted file mode 100644 index 59beda283..000000000 --- a/docs/storefront/catalyst/development/b2b.mdx +++ /dev/null @@ -1,170 +0,0 @@ -# B2B Edition - - -The information in this doc is **deprecated**. - -The current integration is experimental, and the code branch `integrations/b2b-buyer-portal` is deprecated. A more robust guide is in development and will be published soon. - - -Following these steps will help you integrate Catalyst with B2B Edition's Open Source Buyer Portal, which is a traditional client-side rendered React application. The steps below also document the process for running the B2B Buyer Portal React application 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](https://developer.bigcommerce.com/b2b-edition/apis). We've seen this happen organically and are working on streamlining this path as well. - - -Using the default B2B Edition implementation with Catalyst requires support for proxy Customer Access Tokens (CAT). All new B2B Edition stores support this functionality by default. If your store had B2B Edition **prior to July 2025**, you must contact support to enable this feature. - -## Creating and deploying the storefront - -**Prerequisites** - -To create a B2B storefront on the Catalyst platform, you will need the following: - -- A target store. -- Multi-storefront BC and B2B. -- Git and a GitHub account. -- Node.js and PNPM. -- A Vercel account. Using your GitHub account to sign up is recommended for ease. -- A V3 BC API token. -- A V3 B2B API token. You can retrieve this from the B2B control panel under the "API Accounts" tab by clicking "Create API account." Ensure it is a V3 API token. - -### 1. Using Catalyst CLI - -Carefully follow the process at [Manual Installation](/docs/storefront/catalyst/development/manual-installation). Ensure you have met the prerequisites linked at the top of that page. Replace the Catalyst CLI command with: `pnpm create @bigcommerce/catalyst@latest --gh-ref integrations/b2b-buyer-portal`. - -Supply a name for your project and answer all subsequent questions. Connect your BigCommerce account and select the target store. Installing sample data is optional. - -Once the directory is created (it should match your project name), open it and push the fork to your GitHub account. - -### 2. Deploy your fork in Vercel - -Before proceeding with deployment, ensure you set the following environment variables in Vercel. Without these, the build process will not finish successfully. - -The full list of environment variables should include all those listed in the `.env.example` file. If a `.env.local` file was created in the previous step, you can pick the values from there. - -Environment variables to add: - -- BIGCOMMERCE_STORE_HASH -- BIGCOMMERCE_STOREFRONT_TOKEN: Use your store API key to get a storefront token. Refer to the BigCommerce developer documentation for [creating a token](https://developer.bigcommerce.com/docs/rest-authentication/tokens#create-a-token). -- BIGCOMMERCE_CHANNEL_ID -- ENABLE_ADMIN_ROUTE: Default to `true`. -- AUTH_SECRET: Generate it using `openssl rand -hex 32`. -- TURBO_REMOTE_CACHE_SIGNATURE_KEY: Generate using openssl rand -hex 32. -- TRAILING_SLASH: Default to `false`. - -Also add the B2B related environment variables: - -- B2B_API_HOST: https://api-b2b.bigcommerce.com. - - This is the domain of the B2B API. NOTE: Make sure this value does not have a trailing slash. -- B2B_API_TOKEN: The V3 B2B API token obtained during the preparation step. - -Once all environment variables are set, we can proceed with deployment. - -1. Sign in to your Vercel account. You should be redirected to your projects dashboard. -2. Click on `Add new > Project`. -3. Select the repository you created a fork for. If this is your first time deploying with Vercel, you will need to grant access to one or more repositories. It is recommended to give Vercel access only to specific repositories. -4. In the "New Project" form, ensure the framework preset is set to Next.js and the root directory is core. Make sure the project points to the `integrations/b2b-buyer-portal` branch. -5. Click `Deploy`. - -If you need to redeploy your project, go to `Deployments > Create` deployment and specify the desired branch. You can also configure Vercel to automatically monitor for changes and deploy them by going to `Project -> Settings -> Environments` and selecting the desired branch for tracking. - -### 3. Updating Site URL in the Catalyst channel - -By default, BigCommerce creates an automated deploy for merchants. You need to update the URL with your .vercel.app domain where your Catalyst app is hosted. - -Use the following curl command to get all site URLs: - -```sh -curl -X GET \ - https://api.bigcommerce.com/stores//v3/sites \ - -H 'Content-Type: application/json' \ - -H 'X-Auth-Token: ' -``` - -The response will return a list of site objects in your store. Search for the site object where the channel_id matches your Catalyst channel. - -Update the site's URL using the site_id with the following curl command. Make sure to supply your correct .vercel.app domain in the -d argument with the key url: - -```sh -curl -X PUT \ - https://api.bigcommerce.com/stores//v3/sites/ \ - -H 'Content-Type: application/json' \ - -H 'X-Auth-Token: ' \ - -d '{ - "url": "" - }' | jq -``` - -### 4. Enable B2B in the B2B control panel - -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” - -If you have an existing B2B storefront, you may need to [provision B2B Edition on additional storefronts](https://support.bigcommerce.com/s/article/B2B-Edition-and-Multi-Storefront?language=en_US) in order to enable B2B on your Catalyst channel. - -### 5. Configure auth routes and enable storefront redirection - -To allow shoppers to log in (and log out) from the Stencil checkout page and persist their login state back to the Catalyst/headless storefront, follow the step-by-step instructions detailed here: [Checkout Session Syncing Solutions](/docs/storefront/catalyst/development/session-sync). - -## Deploying Catalyst with your custom Buyer Portal - -For a required headless setup using JSX and the Next.js ` - - - - - ); -``` - -Make sure to replace values according to your configuration. If you need further guidance on deploying a custom buyer portal, you can read the documentation here: [Buyer Portal Headless Guide](https://github.com/bigcommerce/b2b-buyer-portal/blob/main/docs/headless.md). - -## Running the project locally - -This step is only required if the merchant wants to run the Buyer Portal locally or customize the Buyer Portal experience. - -- Clone and run the B2B Buyer Portal React application locally: B2B Buyer Portal GitHub Repository -- Set the LOCAL_BUYER_PORTAL_HOST environment variable to the host of the B2B Buyer Portal React application. The default is http://localhost:3001. -- Ensure you configure the Buyer Portal type in your control panel to Custom (step 5 in the B2B Buyer Portal Headless Guide) -- Run pnpm dev from your local Catalyst repository. -- Attempt to log in and confirm you are redirected to the Buyer Portal. - -
- - -If you have any questions or feedback, we'd enjoy hearing it! Start a GitHub Discussion or contact us by [creating a support case.](https://support.bigcommerce.com/s/article/Creating-Viewing-Support-Cases) - diff --git a/docs/b2b-edition/docs/buyer-portal/catalyst.mdx b/docs/storefront/catalyst/experiments/buyer-portal.mdx similarity index 100% rename from docs/b2b-edition/docs/buyer-portal/catalyst.mdx rename to docs/storefront/catalyst/experiments/buyer-portal.mdx