Skip to content

Files

Latest commit

 

History

History
269 lines (205 loc) Β· 12.4 KB

README.md

File metadata and controls

269 lines (205 loc) Β· 12.4 KB
B2B Edition Open Source Buyer Portal

MIT License Lighthouse Report Lint, Typecheck, gql.tada

B2B Buyer Portal is a monorepo frontend application designed for the BigCommerce B2B Edition Buyer portal. The B2B Buyer Portal is built using Turborepo, TypeScript, and React.

By choosing to build on top of our Open Source B2B Buyer Portal, you'll have access to build on our B2B buyer portal application backed by a robust set of SaaS APIs. You can get straight to work building for your unique B2B business cases.

-----------------------------------------------------

πŸš€ B2B Edition β€’ πŸ€— BigCommerce Developer Community β€’ πŸ“ B2B Edition API Reference β€’

-----------------------------------------------------

Index

β˜‘ Prerequisites

Step 1: Ensure you have access to the B2B edition app

If you do not have access to the B2B edition app please reach out to your account or partner manager

Step 2 (optional): Access storefront manager (Only for B2B Multi-storefront and headless stores)

After installing the B2B Edition App, go to the app's dashboard and select the 'Storefronts' section.

b2bNav

Step 3: Enable B2B on Your Channel

Choose the channel where you wish to enable B2B functionality. Initially, B2B features can be activated on a single channel only.

storefront-settings-b2b

Step 4: Contact Us for Additional Support

For assistance with activating the remote buyer portal or to inquire about multi-storefront support, which allows you to utilize B2B features across multiple channels, please reach out to our team at b2b@bigcommerce.com, or raise an issue right here in this repository.

πŸš€ Core Technologies

  • Monorepo Management: Turborepo
  • Type System: TypeScript
  • Frontend Library: React 18
  • Build Tool: Vite

πŸ“¦ Workspaces

  • Application: /apps/storefront - A next-gen B2B Edition storefront application.
    • You can run multiple apps concurrently via turborepo tasks.
  • Packages:
    • /packages/eslint-config-b3 - Shared ESLint configurations.
    • /packages/tsconfig - Shared TypeScript configurations.
    • /packages/ui - A collection of UI components built by B3.
    • /packages/store - A collection of shared store logic.
    • /packages/b3global - A collection of shared global logic.

πŸ›  Tools and Libraries

  • Linting: ESLint
  • Commit Standards: commitlint
  • Git Workflow Tools: Husky, lint-staged
  • UI Framework: MUI 5
  • Routing: React Router 6

πŸ›  System Setup

  • Node: Ensure you have Node.js version >=18.0.0.
  • Package Manager: This project uses Yarn v1.22.17.

βš™ Local Development

  1. Installation of Node and Yarn.
    • For Node, we recommend using nvm.
    • Once Node is installed, you can install Yarn by using npm i -g yarn.
  2. Clone the repository.
  3. Install dependencies using yarn.
  4. Copy environment variables: cp apps/storefront/.env-example apps/storefront/.env.
  5. Update the following values in .env:
  • VITE_ASSETS_ABSOLUTE_PATH: For building for deployment, set this to the URL where the assets folder is hosted. Note that this refers to the absolute URL to the /assets folder, NOT the root/base URL of the build. Remember to also include the trailing slash.

    For example, if you deploy the contents of the dist folder built by running yarn build and hosted it at https://my.custom.cdn/generated/b2b, the value you should put is https://my.custom.cdn/generated/b2b/assets/.

Environment variables have been updated so you can run your UI directly into production storefronts.

  1. Start the development server: yarn dev.
  2. Access to the store through the url i.e: https://my-store.mybigcommerce.com/ or https://my-store.com/ not http://localhost:3001

Running Project Locally

  1. Activate store channel in the Channels Manager.
  2. Configure header and footer scripts:
  • Navigate to Channels Manager -> Scripts.
  • Delete first scripts: B2BEdition Header Script and B2BEdition Footer Script, then
  • Add two scripts (e.g., B2BEdition-header, B2BEdition-footer). Ensure you set the correct port for your localhost in the script URLs. In the "Location" section make sure you check on "All pages".
  • Edit the header script:
<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>
  • Edit the footer script:
<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: https://developer.bigcommerce.com/docs/rest-management/channels#platform
    },
  }
</script>
  1. For local debugging, set VITE_LOCAL_DEBUG to false in .env.

  2. Enable Custom (use for your self-hosted buyer portal), this will avoid the scripts mentioned on step 2 -> 2nd point

  • In B2B Edition App dashboard -> Settings -> Buyer Portal for global config Buyer portal type global settings
  • Or B2B Edition App dashboard -> Storefront -> Desired channel -> Buyer Portal for specific channel config Buyer portal type channel settings alt text
  1. Visit the storefront and attempt to sign in.

  2. For cross-origin issues, update URL variables in .env to use the tunnel URL with HTTPS.

Note: If linters aren't functional, run yarn prepare first.

Deploying the project

Building your buyer portal application requires you to run the yarn build:production command. This command will generate a dist folder in the apps/storefront directory and inside an assets folder containing the compiled assets.

Before building, make sure you have updated your VITE_ASSETS_ABSOLUTE_PATH variable pointing to where the assets folder is hosted as we'll be using this to generate the correct asset paths for the application when its mounted.

Once you have uploaded the contents of the dist folder to your hosting provider, you'll have to create a footer script in your BigCommerce storefront that points to the built files generated in the dist folder. The contents of the script are the same as the footer script B2B Edition installs in your store, but with the updated paths. It should look something like this:

<script>
  window.b3CheckoutConfig = {
    routes: {
      dashboard: '/account.php?action=order_status',
    },
  }
  window.B3 = {
    setting: {
      store_hash: '<YOUR_STORE_HASH>',
      channel_id: '<YOUR_CHANNEL_ID>',
      platform: '<YOUR_STORE_PLATFORM>',
      b2b_url: 'https://api-b2b.bigcommerce.com',
      captcha_setkey: '6LdGN_sgAAAAAGYFg1lmVoakQ8QXxbhWqZ1GpYaJ',
    },
    '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>

Replace <YOUR_APP_URL_HERE> with the URL where your build is hosted, <YOUR_STORE_HASH> and <YOUR_CHANNEL_ID> with its respective values. Replace the * in the file names with the generated hash from the build step.

Also, you'll have to input the following header script:

<script>
  var b2bHideBodyStyle = document.createElement('style')
  b2bHideBodyStyle.id = 'b2b-account-page-hide-body'
  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>

Common issues:

  • Stencil CLI We're working to bring full support to integrate buyer portal into stencil-cli, there are issues on logging out and cart management, if you find other problems feel free to open an issue report.
  • Cross-Origin Issues: If you encounter cross-origin issues, ensure you have the correct URLs in your .env file and verify that your store's origin URL is allowed. You can use a tunnel service like ngrok to expose your local server to the internet.
  • Environment Variables: Ensure you have the correct environment variables set in your .env file. These variables are used to configure your application for different environments.
  • Header and Footer Scripts: Ensure you have the correct header and footer scripts set in your BigCommerce store. These scripts are used to load your application into the storefront.
  • Build Errors: If you encounter build errors, ensure you have the correct dependencies installed and that your project is set up correctly. You can run yarn prepare to ensure all dependencies are installed and up to date.

🀝 Contribution

For developers wishing to contribute, ensure all PRs meet the linting and commit message standards.

πŸ“ž Contact & Support

For queries, issues, or support please open an issue in this repository.

License

MIT