> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Lab - Set Up a Custom Buyer Portal

Plan: B2B Developer

Lesson 10 of 25 · 30 min

## Introduction

This lab will walk you through setting up a local environment running a custom Buyer Portal, as well as connecting this project to your Stencil storefront.

Instead of cloning the main Buyer Portal repository, you'll be setting up a custom repo with boilerplate necessary for subsequent exercises.

### In this lab, you will:

* Copy a Buyer Portal starting repository
* Run a local dev server
* Reconfigure storefront scripts

### Prerequisites

* A BigCommerce [sandbox store](/developer/docs/overview/sandboxes) or [trial store](https://www.bigcommerce.com/essentials/)
* B2B Edition enabled in your store
* A Stencil storefront channel, enabled for B2B
* A command-line interface on your local machine
* Node.js 22 or later
* The [yarn](https://yarnpkg.com/getting-started/install) package manager
* [Git CLI](https://git-scm.com/)

See the [Buyer Portal overview](/developer/docs/b2b-edition/storefront/buyer-portal/overview) in the documentation for details.

## Step 1: Copy the Project

Rather than start your custom code from scratch, you'll be starting from a Buyer Portal codebase that already has certain boilerplate in place, in preparation for subsequent labs.

1. **Install** `degit`, if you didn't install it in the earlier setup lab.

```shell showLineNumbers={false}
npm install -g degit
```

2. **Copy** the starter project, replacing the path to the working directory with your own path.

```shell showLineNumbers={false}
degit https://github.com/bigcommerce-edu/lab-b2b-buyer-portal.git#e-start <directory-name>
```

3. **Navigate** to the new project working directory.

```shell showLineNumbers={false}
cd <directory-name>
```

4. **Initialize** a Git repository for your project.

```shell showLineNumbers={false}
git init
git add .
git commit -m "Initial project files"
```

> **Info**
>
> From here on, we'll leave managing your project's source control to you.

> **Info**
>
> Remember, in these exercises, we're working with a custom starter project with some important boilerplate.
>
> When setting up a new Buyer Portal project of your own, you'll want to [fork the main repository](https://github.com/bigcommerce/b2b-buyer-portal/fork) or clone it directly to start your project:
>
> ```shell showLineNumbers={false}
> git clone git@github.com:bigcommerce/b2b-buyer-portal.git
> ```

## Step 2: Run the Dev Server

1. **Install** the project dependencies.

```shell showLineNumbers={false}
corepack enable yarn && yarn install
```

> **Info**
>
> **Troubleshooting**
>
> The `yarn` command is unrecognized.
>
> In some environments where file permissions are highly restricted, you may need to prepend `corepack` to the use of `yarn` commands (for example, `corepack yarn install`)

2. **Copy** the `.env-example` file.

```shell showLineNumbers={false}
cp apps/storefront/.env-example apps/storefront/.env
```

3. In `.env`, **update** the value of `VITE_B2B_URL` and **add** `VITE_LOCAL_DEBUG`:

**`.env`**

```text showLineNumbers={false} title=".env"
VITE_B2B_URL=https://api-b2b.bigcommerce.com

VITE_LOCAL_DEBUG=TRUE
```

4. **Start** the dev server.

```shell showLineNumbers={false}
yarn dev
```

> **Info**
>
> Just as with the mini app, take note of the `localhost` port displayed in your terminal output. (e.g., `http://localhost:3001`)

## Step 3: Update Storefront Settings

1. **Log into** your BigCommerce control panel.
2. **Navigate** to Script Manager.
3. **Delete** the default "B2BEdition Header Script" and "B2BEdition Footer Script."

> **Warning**
>
> Make sure not to delete these scripts in a store intended for production!

4. **Add** two new Script Manager 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 repo.

See the link above for the latest version of the header and footer scripts.

The **header** script should look something like the following:

```html showLineNumbers={false}
<script>
  {{#if customer.id}}
  {{#contains page_type "account"}}
  var b2bHideBodyStyle = document.createElement('style');
  b2bHideBodyStyle.id = 'b2b-account-page-hide-body';
  b2bHideBodyStyle.innerHTML = 'body { display: none !important }';
  document.head.appendChild(b2bHideBodyStyle);
  {{/contains}}
  {{/if}}
</script>
<script type="module">
  import RefreshRuntime from 'http://localhost:3001/@react-refresh'
  RefreshRuntime.injectIntoGlobalHook(window)
  window.$RefreshReg$ = () => {}
  window.$RefreshSig$ = () => (type) => type
  window.__vite_plugin_react_preamble_installed__ = true
</script>
<script type="module" src="http://localhost:3001/@vite/client"></script>
```

The **footer** script should look something like:

```html showLineNumbers={false}
<script type="module" src="http://localhost:3001/src/main.ts"></script>
<script>
  window.B3 = {
    setting: {
      store_hash: '{{settings.store_hash}}',
      channel_id: {{settings.channel_id}},
      platform: 'bigcommerce', // override this depending on your store channel platform: /developer/api-reference/rest/admin/management/channels
    },
  }
</script>
```

> **Info**
>
> If your dev server is running on a port other than 3001, make sure to update any URLs in the header/footer scripts accordingly.

5. **Navigate** to B2B in the control panel.
6. In the Buyer Portal settings, **set** the "Buyer Portal type" to "Custom".

![Buyer Portal type set to Custom](/_fern-img/3e31ab7b62330438c0827c09d693f090bb7be0acfc21ecec1e27b3baa7407221.webp)

> **Info**
>
> Note that you will find Buyer Portal settings directly under **Settings** in the B2B Edition nav in a single storefront implementation, or in the settings of a specific channel under **Storefronts** if your store supports multi-storefront.

See the [setup guide](/developer/docs/b2b-edition/storefront/buyer-portal/stencil) in the BigCommerce docs for full details of the storefront update.

7. **Navigate** to your Stencil storefront and use the **Account** link in the top nav to verify that the Buyer Portal UI still loads.

![Buyer Portal default UI](/_fern-img/8029c3b9aeced5cf1471884541c3ebe6c76cca0c92a36c6a16d17be957022754.webp)

> **Info**
>
> **In Catalyst**
>
> As previously mentioned, the process for injecting the Buyer Portal is different in Catalyst. This method involves scripts managed directly in the Catalyst codebase, not via Script Manager.
>
> See the [Catalyst guide](/developer/docs/storefront/catalyst/experiments/b2b-edition) for full details on swapping in your custom Buyer Portal.

## Step 4: Hello World

> **Info**
>
> In this step and all subsequent exercises, file paths are relative to `apps/storefront/src` in your Buyer Portal project.

1. **Open** the file `pages/order/Order.tsx`.
2. In the first `Box` component in the JSX returned from `Order`, **add** a "Hello World" block.

**`Order.tsx`**

```tsx {11} showLineNumbers={false} title="Order.tsx"
function Order({ isCompanyOrder = false }: OrderProps) {
  ...

  return (
    <B3Spin isSpinning={isFetching}>
      <Box
        sx={{
          ...
        }}
      >
        <h1>Hello World</h1>
        ...
      </Box>
    </B3Spin>
  );
}
```

3. **Browse** to the "My orders" or "Company orders" page in the Buyer Portal and verify that your message is displayed.

![Hello world in the Buyer Portal](/_fern-img/e4cccb3e42d43f2bc951046df0d5bcaf729a596ca6c442e1aaa23e8ec4ecc677.webp)

You've successfully connected your Stencil storefront to your local Buyer Portal project!

Feel free to remove your "Hello World" block before proceeding.

## Resources

* [Buyer Portal Overview](/developer/docs/b2b-edition/storefront/buyer-portal/overview)
* [Fork the Buyer Portal Repo](https://github.com/bigcommerce/b2b-buyer-portal/fork)
* [Stencil Guide (GitHub)](https://github.com/bigcommerce/b2b-buyer-portal/blob/main/docs/stencil.md)
* [Stencil Setup Guide (Docs)](/developer/docs/b2b-edition/storefront/buyer-portal/stencil)
* [Catalyst Guide](/developer/docs/storefront/catalyst/experiments/b2b-edition)