Configuration

What configuration does

Configuration tells the package which store you are. Every method uses this value automatically — you never pass the tenant UID per call.

Setting	Purpose
`tenant`	Your store ID → `x-tenant` header
`accessToken`	Optional — restore a logged-in customer

The SDK connects to the hosted StoreOS API by default. Pass baseUrl only when pointing at a local or self-hosted API.

Environment variables

In .env.local:

NEXT_PUBLIC_SITE_API_TENANT=your-tenant-uid
NEXT_PUBLIC_SITE_URL=https://my-store.com

→ What each variable means

Create the client

import { StoreFront } from "@storeos/storefront-client";

export const store = new StoreFront({
  tenant: process.env.NEXT_PUBLIC_SITE_API_TENANT!,
});

Options

Option	Required	What it does
`tenant`	Yes	Identifies your store on every API call
`baseUrl`	No	Override API host — for local dev or self-hosted APIs
`accessToken`	No	Customer JWT — pass when restoring a saved session
`fetch`	No	Override `fetch` for tests or edge runtimes

Customer sessions

What the SDK does: Keeps the JWT in memory after login, register, or verifyOtp.

What your app must do: Save and restore that token across page loads.

// After login
await store.login({ user: "jane@example.com", password: "…" });
const token = store.getAccessToken();
// → cookie, localStorage, or your auth layer

// On next visit
store.setAccessToken(tokenFromCookie);
const me = await store.getMe();

Guest checkout: createOrder may return authToken so the customer can track the order — the SDK stores it automatically.

One client vs per-request

Single shared client — fine for most apps:

// lib/store.ts — export one instance
export const store = new StoreFront({ … });

Per-request client — for SSR when each user has their own cookie:

const store = new StoreFront({
  tenant: process.env.NEXT_PUBLIC_SITE_API_TENANT!,
  accessToken: cookies().get("token")?.value,
});

Next.js notes

No special bundler config. Use in Server Components, Route Handlers, or client components wherever fetch is available.

→ Methods — REST methods after setup
→ React SDK — providers, GraphQL, cart, and server helpers