Lab - Set Up a Custom Buyer Portal

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 or trial store
• 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 package manager
• Git CLI

See the 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.

npm install -g degit

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

degit https://github.com/bigcommerce-edu/lab-b2b-buyer-portal.git#e-start <directory-name>

3. Navigate to the new project working directory.

cd <directory-name>

4. Initialize a Git repository for your project.

git init
git add .
git commit -m "Initial project files"

git clone git@github.com:bigcommerce/b2b-buyer-portal.git

Step 2: Run the Dev Server

1. Install the project dependencies.

corepack enable yarn && yarn install

2. Copy the .env-example file.

cp apps/storefront/.env-example apps/storefront/.env

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

VITE_B2B_URL=https://api-b2b.bigcommerce.com
VITE_LOCAL_DEBUG=TRUE

4. Start the dev server.

yarn dev

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.”

4. Add two new Script Manager entries for header and footer scripts as described in the Stencil Guide 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:

<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:

<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>

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

See the setup guide 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.

Step 4: Hello World

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.

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.

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
• Fork the Buyer Portal Repo
• Stencil Guide (GitHub)
• Stencil Setup Guide (Docs)
• Catalyst Guide