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	— (your app)	`useCart` (localStorage)
Checkout	`createOrder`, `verifyCoupon`	Mutations + Zod form schemas
Orders	`getMyOrders`, `cancelOrder`, …	Queries + server session helpers

REST reference: Methods
React reference: React SDK

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, cart and session persistence are also yours. With the React SDK, cart 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 add

React 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 next

Quick 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

TypeScript SDK

On this page