Subbly React

React hooks and providers for building Subbly storefronts, wrapping @subbly/kit with state management for carts, products, bundles, subscriptions and customers.

Installation

From the package manager of your choice:

npm install @subbly/react
# or
yarn add @subbly/react

React 19 is a peer requirement.

Usage

Initialize the shared API instance once, as early as possible:

import { subblyApi } from '@subbly/react';

subblyApi.initialize({ apiKey: 'API_KEY' });

Note: You can find your API key on the Storefront API keys page in Subbly Admin.

Then use the hooks:

import { useSubblyCart } from '@subbly/react';

export function AddToCartButton({ productId }) {
  const { addToCart } = useSubblyCart();

  return <button onClick={() => addToCart({ productId })}>Add to cart</button>;
}

Hooks are grouped by domain — cart (useSubblyCart, useBuyLink), product (useProductForm, useProductImages, useVariantCombinations), bundle, subscription, customer and currency.

SubblyProvider and CustomerPortalProvider are exported for features that need context; SubblyProvider is currently a passthrough and is not required to use the hooks.

Server components

A react-server export condition resolves to a server-safe entry exposing only the API instance, so importing it from a React Server Component pulls in no client-side hooks:

import { subblyApi } from '@subbly/react';

License

MIT