@colossal-sh/storefront-sdk

React hooks and helpers for building Colossal storefronts. Wraps the Colossal Storefront GraphQL API with type-safe hooks for products, cart, and checkout.

Note — this package is published primarily to showcase the SDK and power Colossal's starter templates. The source is mirrored from a private monorepo, and external contributions, issues, and local builds are not currently supported. For bug reports and feature requests, reach out via the Colossal dashboard or docs feedback.

Install

npm install @colossal-sh/storefront-sdk @tanstack/react-query

Peer dependency: react ^18 || ^19.

Quick start

// main.tsx
import {
  CartProvider,
  initStorefrontClient,
} from "@colossal-sh/storefront-sdk";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

initStorefrontClient({
  url: import.meta.env.VITE_API_URL,
  getHeaders: () => ({ "X-Store-Uid": STORE_UID }),
});

const queryClient = new QueryClient();

export function Root({ children }) {
  return (
    <QueryClientProvider client={queryClient}>
      <CartProvider storeUid={STORE_UID} currency="USD">
        {children}
      </CartProvider>
    </QueryClientProvider>
  );
}

import { useProducts, useCartContext } from "@colossal-sh/storefront-sdk";

function ProductGrid() {
  const { products, isLoading } = useProducts(STORE_UID);
  const { addItem } = useCartContext();

  if (isLoading) return null;

  return products.map((p) => (
    <button key={p.uid} onClick={() => addItem(p.uid)}>
      {p.name} — {p.formattedPrice}
    </button>
  ));
}

What's in the SDK

• Setup — initStorefrontClient, <CartProvider>
• Products — useProducts, useProduct, useStoreProducts, useStoreProduct
• Cart — useCartContext (high-level), plus useCart, useCreateCart, useAddToCart, useUpdateCartLine, useRemoveCartLine for low-level access
• Checkout — useCreateCheckoutSession
• Store / workspace — useStore, useCurrentStore
• Imperative fetchers — fetchProducts, fetchProduct, fetchStore, etc. for SSR / route loaders
• Custom GraphQL — executeStorefront and the typed graphql tag
• Helpers — formatPrice, toSimpleProduct, toSimpleLineItem, plus product/line-item accessors

Documentation

Full reference and guides:

• Storefront SDK overview
• Products
• Cart
• Checkout
• Storefront API reference

Starter template

The fastest way to get running is the official Vite starter, which wires up the SDK end to end:

npm create colossal-project my-store

Source: colossalhq/colossal-storefront-starter-vite.

License

Proprietary. © Colossal.