TypeScript SDK
StoreOS TypeScript SDK
What @storeos/storefront-client is — REST client and React SDK for StoreOS storefronts.
What is this package?
@storeos/storefront-client is an npm package that connects your storefront app to StoreOS. It ships two surfaces from the same package:
| Surface | Import | Transport | Best for |
|---|---|---|---|
| REST client | @storeos/storefront-client | REST /api/v1 | Any runtime with fetch |
| React SDK | @storeos/storefront-client/react | GraphQL + providers/hooks | Next.js / React storefronts |
Both surfaces send x-tenant, attach auth when present, and return typed data.
What the package does
| Area | REST client | React SDK |
|---|---|---|
| Catalog | getProducts, getProduct, … | GraphQL queries + gqlClient |
| Auth | login, register, OTP, … | useAuth, cookie session helpers |
| Cart | upsertCart, getCart, deleteCart | useCart (server cart + local mirror) |
| Checkout | createOrder, verifyCoupon | Mutations + Zod form schemas |
| Orders | getMyOrders, cancelOrder, … | Queries + server session helpers |
What the package does NOT do
| Your app's job | Why it's yours |
|---|---|
| UI & pages | Branding, layout, design system |
| Deploy & domain | Hosting your storefront |
| Payment UI | Collecting card details for ONLINE orders |
With the REST client alone, you keep the cartId and call the cart methods yourself. Session persistence is also yours. With the React SDK, cart sync and cookie-backed auth are included — you still build the UI around them.
Package vs your app
| Concern | Package | Your app |
|---|---|---|
| HTTP / GraphQL to StoreOS | ✅ | |
| Tenant + auth headers | ✅ | |
| TypeScript types | ✅ | |
| React providers & hooks (React SDK) | ✅ | |
| Pages, routing, design | ✅ | |
| Deploy | ✅ |
Install
npm install @storeos/storefront-client
# or: yarn add / pnpm add / bun addReact SDK peers (when using /react):
npm install react react-dom @tanstack/react-query zod immer use-immer
# optional — Next.js App Router server helpers
npm install nextQuick starts
REST
// lib/store.ts
import { StoreFront } from "@storeos/storefront-client";
export const store = new StoreFront({
tenant: process.env.NEXT_PUBLIC_SITE_API_TENANT!,
});
const { nodes: products } = await store.getProducts({ limit: 24 });Default API host: https://storefront-api.storeos.dev.
React
"use client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { StoreOSProvider } from "@storeos/storefront-client/react";
const queryClient = new QueryClient();
export function Providers({ children }: { children: React.ReactNode }) {
return (
<QueryClientProvider client={queryClient}>
<StoreOSProvider
config={{
tenant: process.env.NEXT_PUBLIC_SITE_API_TENANT!,
siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
}}
>
{children}
</StoreOSProvider>
</QueryClientProvider>
);
}→ Full React setup: React SDK
Next steps
- Configuration — REST env vars, sessions, Next.js
- Methods — REST method reference
- React SDK — providers, hooks, GraphQL, server helpers
- REST API · Swagger