Lab - Deploying Your Buyer Portal

Introduction

You’ve spent several exercises customizing your own fork of the B2B Buyer Portal. Loading this custom code into your Stencil storefront from your locally running server has worked well so far, but of course you ultimately need your Buyer Portal to be deployed and available from a publicly accessible URL.

In this exercise, we’ll practice deploying your Buyer Portal via the built-in WebDAV storage available in your BigCommerce store.

In this lab, you will:

• Build your Buyer Portal assets
• Deploy Buyer Portal files to your store’s WebDAV storage
• Update your store’s header/footer scripts to load the production-ready Buyer Portal

Prerequisites

• A local Buyer Portal project as completed in previous lab exercises
• 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
• A WebDAV client configured with your store’s WebDAV credentials

Setup

This exercise continues where you left off previously. If you want to start with a fresh copy of the completed project (for example, if you encounter any build errors), you can use the following command to clone the finished state:

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

Don’t forget to copy .env-example as .env.

Step 1: Determine Your Base URL

Before we build the Buyer Portal assets, we need to determine the fully qualified URL where these assets will ultimately reside.

Once we get to the step of deploying the Buyer Portal files to your store’s WebDAV storage, we will be uploading them to a specific subdirectory: content/b2b-1.0/.

This relative path will be appended directly to your store’s base URL. This base URL is the same URL you use to browse to the storefront (and can also be found in your control panel with the “View storefront(s)” link in the top navigation bar.)

Buyer Portal Base URL: https://<my-store-domain>/content/b2b-1.0/

Step 2: Build the Buyer Portal Assets

1. Open .env in your Buyer Portal project and edit or add vars as follows.

2. Run the build command from the root directory of your project.

yarn build

After building, apps/storefront/dist should contain the final Buyer Portal assets.

Step 3: Upload to WebDAV Storage

1. Open your WebDAV client (e.g., Cyberduck) and connect to your store’s WebDAV storage.
2. Upload the dist directory from apps/storefront into the content directory in WebDAV.

With a client like Cyberduck, it’s easiest to open your project in your file manager and drag dist into the content folder in the client app.

3. In your WebDAV client, rename the dist directory to b2b-1.0.

The result should be a viable public URL on your storefront in this form:

https://<my-store-domain>/content/b2b-1.0/index.js

4. Verify that your Buyer Portal files have been uploaded to the correct location by browsing directly to the index.js URL in the form shown above.

Your browser should render the raw content of the index.js file.

Step 4: Update Storefront Settings

Your storefront scripts are currently loading the Buyer Portal assets from your local development server. We need to update them to load the production-ready assets from your store’s WebDAV storage. More than just the file paths will differ with these scripts.

1. Log into your BigCommerce control panel.
2. Navigate to Script Manager.
3. Update the header script 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>
var b2bHideBodyStyle = document.createElement('style');
b2bHideBodyStyle.id = 'b2b-account-page-hide-body';
{{#if customer.id}}
  {{#contains page_type "account"}}
    b2bHideBodyStyle.innerHTML = 'body { display: none !important }';
    document.head.appendChild(b2bHideBodyStyle);
  {{/contains}}
{{/if}}
{{#if page_type "login"}}
  b2bHideBodyStyle.innerHTML = 'body { display: none !important }';
  document.head.appendChild(b2bHideBodyStyle);
{{/if}}
const removeCart = () => {
  const style = document.createElement('style');
  style.type = 'text/css';
  style.id = 'b2bPermissions-cartElement-id'
  style.innerHTML='[href="/cart.php"], #form-action-addToCart, [data-button-type="add-cart"], .button--cardAdd, .card-figcaption-button, [data-emthemesmodez-cart-item-add], .add-to-cart-button { display: none !important }'
  document.getElementsByTagName('head').item(0).appendChild(style);
}
removeCart()
</script>

4. Save the header script.
5. Update the footer script as described in the Stencil Guide.

The footer script should look something like:

<script>
  window.b3CheckoutConfig = {
    routes: {
      dashboard: '/account.php?action=order_status',
    },
  }
  window.B3 = {
    setting: {
      store_hash: '{{settings.store_hash}}',
      channel_id: {{settings.channel_id}},
      platform: 'bigcommerce'
    },
    'dom.checkoutRegisterParentElement': '#checkout-app',
    'dom.registerElement':
      '[href^="/login.php"], #checkout-customer-login, [href="/login.php"] .navUser-item-loginLabel, #checkout-customer-returning .form-legend-container [href="#"]',
    'dom.openB3Checkout': 'checkout-customer-continue',
    before_login_goto_page: '/account.php?action=order_status',
    checkout_super_clear_session: 'true',
    'dom.navUserLoginElement': '.navUser-item.navUser-item--account',
  }
</script>
<script
  type="module"
  crossorigin=""
  src="<YOUR_APP_URL_HERE>/index.*.js"
></script>
<script
  nomodule=""
  crossorigin=""
  src="<YOUR_APP_URL_HERE>/polyfills-legacy.*.js"
></script>
<script
  nomodule=""
  crossorigin=""
  src="<YOUR_APP_URL_HERE>/index-legacy.*.js"
></script>

6. Modify the footer script to replace <YOUR_APP_URL_HERE> with the Buyer Portal base URL determined in the previous steps, as well as to remove the *. from each filename.

Example:

<script
  type="module"
  crossorigin=""
  src="https://<my-store-domain>/content/b2b-1.0/index.js"
></script>

7. Save the footer script.

With your new scripts in place, navigate to your storefront. Verify that your custom Overview page functionality still works. Watch the network tab in your browser dev tools to verify that index.js is loading from your deployed location.

Final Considerations

Switching Back to Local Development

To summarize the steps required to switch your storefront back to using the local Buyer Portal server:

1. Update .env to set VITE_IS_LOCAL_ENVIRONMENT to TRUE.
2. Run yarn dev to start the local dev server.
3. Update your header and footer scripts in Script Manager to the appropriate scripts from the Stencil Guide.

Subsequent Deployments

As you go through development cycles to iterate on your custom Buyer Portal, subsequent deployments should involve the following:

1. Formulate a new base URL for your Buyer Portal assets. (e.g., https://<my-store-domain>/content/b2b-1.1/)
2. Update .env to set VITE_ASSETS_ABSOLUTE_PATH to the new base URL.
3. Repeat the steps for building and deploying your assets.
4. Update the footer script in Script Manager with the new base URL.

Note that because we’re using a directory-based strategy (b2b-1.1) for versioning, the previously deployed version of the Buyer Portal will continue to be used up until your footer script is updated. If there are any issues with the new version, reverting is as easy as updating your footer script back to the old URL.

The Build Hash

Our inclusion of a unique directory with a version number in the assets URL is an example of “cache busting.” Because the assets’ URLs change when you deploy a new version, Buyer Portal functionality will not be disrupted by stale cached assets.

You might also choose to use a date-based directory name, such as b2b-20270101.

Contrasting with a directory-based approach, you might also choose to use the built-in build hash for versioning and cache busting. Enable this default behavior by removing VITE_DISABLE_BUILD_HASH from .env before building.

With the default hash behavior, each build file will be suffixed with a hash value (e.g., index.<hash>.js). If you rely on this approach for cache busting, you might be using a URL like the following in Script Manager:

https://<my-store-domain>/content/b2b/index.<hash>.js

The benefits of the hash approach are that you don’t have to manually create a version naming convention, and that VITE_ASSETS_ABSOLUTE_PATH can remain consistent rather than changing with each new version. The downside is that you will always overwrite your previous build files when deploying, making the old build files immediately inaccessible and making it more complicated to roll back to a previous build.

Bring Your Own CDN

In this exercise, we’ve used the built-in WebDAV storage available in your BigCommerce store to host your Buyer Portal assets. This is a viable option for production stores as well as sandbox scenarios.

However, you might prefer to use a third-party CDN to host your build files, based on your infrastructure needs or your organization’s policies or existing services. Buyer Portal static assets can be loaded from any publicly accessible URL. Just make sure to pre-determine the base URL where your assets will be available and set VITE_ASSETS_ABSOLUTE_PATH accordingly before building.

More Information

See the Buyer Portal documentation regarding building and deploying.

Resources

• Cyberduck
• WebDAV Configuration
• Stencil Guide
• Build/Deploy Guide