Gesso BigCommerce

Installation

pnpm add @acromedia/gesso-bigcommerce @acromedia/gesso-commerce pnpm add -D @acromedia/gesso-cli

@acromedia/gesso-commerce is a peer dependency and needs to be installed as well.

Usage

1. set the GESSO_BIGCOMMERCE_XAUTH_TOKEN and GESSO_LOCAL_URL env values, either in .env or directly
   • The xauth-token you can get from BigCommerce dashboard or 1pass for testing
   • The local url should be your testing url, like localhost:3000 for nextjs or localhost:8082 for directly working on this lib
2. run pnpm gesso config bigcommerce to generate a gesso.config.json
3. If you're adding this module for the first time and want to construct the provider, run pnpm gesso construct commerce
4. import the commerce file to use the commerce hooks

import { useProduct } from './commerce.ts';

1. If you plan on using useCart() in your project, an API proxy needs to be defined in your project. If you're using the starter kit this is already done for you.
   1. Install the proxy package in your frontend project with the command: pnpm add next-http-proxy-middleware
   2. Create a new api folder inside the pages directory
   3. Copy the bigcommerce api route [[…route.ts]] from the starter kit

Feel free to renamed or move the generated file as you see fit.

Examples

Basic

Product Search

Hook that just supplies data

import commerce from 'commerce';

const { useProductSearch } = commerce;

const Catalog = (props): JSX.Element => {
  const products = useProductSearch('', {}, ['23'], 50);

  console.log(products);

  return <>Products</>;
};

Loading Product by sku

const { useProduct } = commerce;
const product = useProduct(sku);

See Product.spec.tsx for more in depth examples.

Advanced

Hook that supplies data and functions. In this example, cart provides the cart contents via cart as well as functions to perform add, update and remove operations on the cart. Cart will keep track of its own state and update automatically.

   import commerce from '../commerce.ts';

   const { useCart } = commerce;

   const Cart = (props): JSX.Element => {
      const { cart, add, update, remove } = useCart();

      const addHandler = (id: string) => {
         add(id, 1);
      };

      const updateHandler = () => {
         update(cart.items[0], 2);
      };

      const removeHandler = () => {
         remove(cart.items[0]);
      };

      const outputCartItem = (item: CartItem) => (
         <li>
            <ul>
            <li>id: {item.id}</li>
            <li>productId: {item.productId}</li>
            <li>quantity: {item.quantity}</li>
            </ul>
         </li>
      );

      return (
         <>
            cartId: {cart.id}
            <ul>{cart.items?.map((item) => outputCartItem(item))}</ul>
            <button onClick={() => addHandler('86')}>Add1</button>
            <button onClick={() => addHandler('107')}>Add2</button>
            <button onClick={updateHandler}>Update</button>
            <button onClick={removeHandler}>Remove</button>
         </>
      );
   };

Additionally, the tests for this module as well as the tests for Gesso Commerce offer examples of how every hook works.

Testing

By default, cart and customer tests will run against mocks. If you want to run against the live API, add 'LIVE_TESTS=true' to your env