Skip to content
Browse documentation

Ecommerce SDK overview

@nanosite/ecommerce-sdk is the typed client for NanoSite's headless commerce backend. Your storefront — whether one of our templates or a custom frontend — talks to the commerce engine through this SDK, never with raw fetch calls.

What you get

The SDK gives you:

  • a fully typed fetch client, and
  • TanStack React Query hooks for every endpoint.

You get end-to-end types from the commerce API to your React components, so your storefront never has to hand-write request or response shapes.

Every query hook ships in two flavors: a standard hook (e.g. useListStoreProducts) and a Suspense variant (useListStoreProductsSuspense) for use with React <Suspense> boundaries.

Configuring the SDK

Call configureEcommerceSdk once when your app starts:

import { configureEcommerceSdk } from "@nanosite/ecommerce-sdk";

configureEcommerceSdk({
  baseUrl: "",                     // API origin; "" for same-origin in the browser
  publishableKey: "pk_live_…",     // storefront (public) endpoints
  // adminToken: "…",              // optional: admin endpoints
  // headers: { Cookie: "…" },     // optional: forward the shopper's cookie (SSR)
});
Option Purpose
baseUrl The commerce API origin (no trailing slash). Use "" for same-origin browser requests.
publishableKey Public key (pk_…) that scopes storefront requests to your store. Safe to ship to the browser.
adminToken Admin credential for /api/admin/* endpoints (store management). Never expose to shoppers.
headers Extra headers to attach — used server-side to forward the shopper's session cookie.

The SDK's request layer attaches the right credential per endpoint automatically: admin endpoints get the adminToken; storefront endpoints get the publishableKey, and the shopper's session rides along as an httpOnly cookie (credentials: "include").

Non-2xx responses throw an EcommerceApiError carrying the HTTP status and parsed body.

Server-side rendering

Storefronts are server-rendered. For SSR, import the server entry and wrap each render so concurrent requests for different stores never clobber a shared config:

import { runWithSdkConfig } from "@nanosite/ecommerce-sdk/server";

await runWithSdkConfig(
  { baseUrl, publishableKey, headers: { Cookie: req.headers.cookie ?? "" } },
  () => renderApp(),
);

runWithSdkConfig uses an AsyncLocalStorage-backed per-request resolver. Browser bundles must not import the /server entry (it relies on node:async_hooks).

The hook surface

The SDK exposes hooks grouped by audience:

  • Storefront (read) — useListStoreProducts, useGetStoreProduct, useGetRelatedProducts, useListStoreCollections, useGetCart, useGetStoreOrder, useGetStoreSettings, useGetShippingRates, useGetCurrentCustomer, useListCustomerOrders, useListCustomerFields, and more.
  • Storefront (mutations) — useCreateCart, useAddLineItem, useUpdateLineItem, useRemoveLineItem, useApplyDiscount, useCheckout, useCaptureOrderPayment, useRegisterCustomer, useLoginCustomer, useUpdateCurrentCustomer (profile + custom fields), useTrackEvent, and more. Custom fields on customers: see Customers & custom fields.
  • Admin — product/order/customer/collection/promotion management, customer custom fields, settings, payments, shipping, tax, team, uploads, analytics, translations, marketing destinations, review moderation, email templates, and useListAdminSubscriptions.

Each generated hook also ships raw helpers (get<Name>QueryKey, get<Name>Url, and a plain client function) for use outside React.

Next: the domains these hooks operate on — Products & subscriptions, Payments, and Webhooks & events.