Getting Started

What you're building

A storefront app is the website your customers use — product pages, cart, checkout, login. StoreOS is the backend behind it. This guide connects the two.

You will:

1. Create a frontend project (your repo)
2. Install @storeos/storefront-client (talks to StoreOS)
3. Point at the hosted API with your tenant UID
4. Fetch catalog data and build pages
5. Run and deploy your app

You will not: set up the StoreOS server, clone a monorepo, or use workspace:*.

What you need before starting

Step 1 — Create your app

Your storefront lives in your own repository:

bun create next-app my-store
cd my-store

This is where you build UI, routing, and branding. StoreOS only provides data via the API.

Step 2 — Install the package

@storeos/storefront-client wraps the StoreOS REST API — catalog, auth, checkout, orders — with typed methods.

bun add @storeos/storefront-client

→ What the package does

Step 3 — Configure environment variables

Create .env.local:

NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_SITE_API_TENANT=your-tenant-uid

→ Environment variables

Step 4 — Create a StoreOS client

One shared client for your app:

// lib/store.ts
import { StoreFront } from "@storeos/storefront-client";

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

The client knows your tenant and connects to the hosted StoreOS API automatically. Import store on any page that needs products, auth, or orders.

Step 5 — Make your first request

Catalog — list products for your shop page:

const { nodes: products } = await store.getProducts({ limit: 12 });

Store config — delivery charges, policies:

const tenant = await store.getTenant();

→ First API request — REST, GraphQL, and curl examples

Step 6 — Build pages and launch

bun dev    # your app on localhost:3000
           # API is already live at storefront-api.storeos.dev

Deploy to Vercel, Cloudflare, or your host. Your app keeps calling StoreOS over HTTPS.

→ Guides · SDK methods

Choose how to call the API