@webround/commerce-react

The hooks that bind @webround/commerce to React components (React 19 or later). They only bind: the rules are in the logic below. There is no Provider: a module of the site makes the store once and components import it.

import { commerce } from '@webround/commerce-react/site'; // the store of this site
import { useShop, useAuth, useCart, useCheckout } from '@webround/commerce-react';

Hook	What it gives
useResource(resource)	Any question to the catalog, as { status, data, error, isFetching, isStale, retry }.
useShop({ catalog, context })	The shop: state, actions, storeData, sortOptions, question and results.
useShopAddress({ search, navigate, collectionId?, limit? })	Keeps the shop's state in the address, with any router. Use it as useShop({ store: useShopAddress(...) }).
useAuth(commerce.auth)	state, status, customer, challenge and actions (signup, login, verifyTwoFactor, cancelChallenge, logout).
useCart(commerce)	state, count, priced and actions (add, setQuantity, remove, clear, refresh).
useCheckout(commerce)	state, quote and actions (the customer's choices, quote, pay, reset, complete).
useAccount, useAddresses	The customer's account requests and address book.
useOrders, useOrder, useSubscriptions, useSubscription	What the customer bought, a page at a time.
useReturnRequests, useReturnRequest, useGuestReturnSession(commerce, token)	Returns, for a customer and for a guest.
useWishlist(commerce)	count, has(variantId) and toggle.
useMyReviews, useReviewAbility	The customer's reviews, and whether they can write one (login, verify, allowed).

A listing

function Shop() {
  const { state, actions, results } = useShop({
    catalog: commerce.catalog,
    context: { currencyCode: 'EUR', langCode: 'default' },
  });

  if (results.status === 'error') return <button onClick={results.retry}>Try again</button>;
  return (
    <>
      {results.data?.data.map((product) => <ProductCard key={product.id} product={product} />)}
      <button onClick={() => actions.setPage(state.page + 1)}>More</button>
    </>
  );
}

keepPrevious is on by default, so the listing does not empty at every click: results.isStale says the products shown are the ones before.

The customer and the cart

const { status, customer, actions } = useAuth(commerce.auth);
await actions.login({ email, password }); // throws what the store says: show it in the form

const { count, priced, actions: cart } = useCart(commerce);
cart.add({ variantId, priceId, quantity: 1 });

The first component that mounts takes the customer back (once); a server render says unknown and asks nothing. A cart shows its lines at once (count) and the store's price when it has it (priced, with state.isStale if it is one change behind).

Paying

const { quote, actions } = useCheckout(commerce);

async function pay() {
  const { url } = await actions.pay();
  location.assign(url); // the payment page
}

useCheckout asks for the preview by itself when the cart or the customer's choices change (autoQuote: false turns that off); a refusal is in state.error, not thrown. On the success page call actions.complete().