Quickstart

The fastest production path is the unified TypeScript SDK. Public catalog reads do not require a user session; cart, authentication, account, and order flows use an anonymous or logged-in session.

You need a Commerce Engine Store ID and publishable Storefront API key from the Admin Portal. The Storefront API key is intended for storefront clients and is scoped by Commerce Engine. Do not confuse it with private admin or payment-provider credentials.

1. Install the SDK

npm install @commercengine/storefront

For AI-assisted implementation, also install the Commerce Engine skills package:

npx skills add commercengine/skills

2. Set environment variables

Use the public environment-variable prefix required by your framework:

# Vite / TanStack Start
VITE_STORE_ID=your-store-id
VITE_API_KEY=your-api-key
VITE_CE_ENV=staging

# Next.js
NEXT_PUBLIC_STORE_ID=your-store-id
NEXT_PUBLIC_API_KEY=your-api-key
NEXT_PUBLIC_CE_ENV=staging

# Astro / SvelteKit
PUBLIC_STORE_ID=your-store-id
PUBLIC_API_KEY=your-api-key
PUBLIC_CE_ENV=staging

Keep an .env.example in the repository and exclude real .env files from version control.

3. Initialize the SDK

For a browser SPA:

lib/storefront.ts

import {
  BrowserTokenStorage,
  Environment,
  createStorefront,
} from "@commercengine/storefront";

export const storefront = createStorefront({
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  environment:
    import.meta.env.VITE_CE_ENV === "production"
      ? Environment.Production
      : Environment.Staging,
  session: {
    tokenStorage: new BrowserTokenStorage("myapp_"),
  },
});

export const publicSdk = storefront.public();
export const sdk = storefront.session();

For Next.js, TanStack Start, Astro, or SvelteKit, use the first-party framework wrapper instead of the SPA factory:

Next.js

App Router, Server Components, Server Actions, SSG/ISR, and cookie-backed sessions.

TanStack Start

Route loaders, prerendering, server functions, and client sessions.

Astro

Static/SSR pages, islands, middleware, and request cookies.

SvelteKit

Universal loads, server loads, actions, hooks, and cookie-backed sessions.

4. Make a public catalog request

Public reads are publishable-key-backed and do not create anonymous users or write session storage.

const { data, error } = await publicSdk.catalog.listProducts({
  page: 1,
  limit: 20,
});

if (error) {
  console.error(error.message);
} else {
  console.log(data?.products ?? []);
}

Use public accessors for products, categories, search, recommendations, and store configuration when the response does not depend on a live user session.

5. Start a live session

Cart, wishlist, authentication, customer, order, and payment operations use the session accessor. You may establish the anonymous session eagerly at application startup:

await sdk.ensureAccessToken();

Most session methods can also ensure the session internally. Centralize eager bootstrap once rather than calling ensureAccessToken() before every feature request. Create the cart with the first item—Commerce Engine does not create empty carts:

const { data, error } = await sdk.cart.createCart({
  items: [
    {
      product_id: "product-id",
      variant_id: null,
      quantity: 1,
    },
  ],
});

if (error) {
  console.error(error.message);
} else {
  console.log(data?.cart);
}

For products with variants, pass the resolved variant_id; for products without variants, pass null.

6. Add Hosted Checkout

Hosted Checkout is the recommended checkout implementation for most storefronts. It supplies the cart drawer, authentication, addresses, fulfilment, coupons, loyalty, payments, and confirmation UI.

npm install @commercengine/checkout

When the Storefront SDK is present, it must own the session. Initialize checkout with authMode: "provided" and synchronize token changes in both directions. Follow the framework-specific pattern:

Hosted Checkout overview

Architecture, package selection, and integration choices.

Configuration

Authentication modes, callbacks, methods, events, and Quick Buy.

7. Retrieve exact SDK contracts

Before implementing a feature, retrieve the current operation and schema definitions from the LLM-first reference:

curl -H "Accept: text/markdown" \
  https://llm-docs.commercengine.io/storefront/operations/create-cart

Agents without custom-header support can append .md:

https://llm-docs.commercengine.io/storefront/operations/create-cart.md

Direct REST integration

Use direct REST calls when you are building a non-TypeScript client, an integration that cannot use the SDK, or a custom backend façade. In that mode you are responsible for token storage, refresh, retry, and response-envelope handling.

Staging base URL: https://staging.api.commercengine.io/api/v1/{store_id}/storefront
Production base URL: https://prod.api.commercengine.io/api/v1/{store_id}/storefront

Public operations can use the publishable API key where declared by the operation contract. Live session operations use Bearer tokens obtained through /auth/anonymous, login, or refresh flows. Use the generated API reference for exact per-operation security requirements.

Next steps

Production storefront

Full agent execution contract and production validation gates.

Catalog

Product, Item/SKU, variant, search, and PDP decisions.

Authentication

Anonymous, OTP, password, login, logout, and session continuity.

Cart

First-add behaviour, cart mutation, recovery, discounts, and totals.

Getting Started

Storefront Guides

AI-Assisted Development

1. Install the SDK

2. Set environment variables

3. Initialize the SDK

Next.js

TanStack Start

Astro

SvelteKit

4. Make a public catalog request

5. Start a live session

6. Add Hosted Checkout

Hosted Checkout overview

Configuration

7. Retrieve exact SDK contracts

Direct REST integration

Next steps

Production storefront

Catalog

Authentication

Cart

​1. Install the SDK

​2. Set environment variables

​3. Initialize the SDK

Next.js

TanStack Start

Astro

SvelteKit

​4. Make a public catalog request

​5. Start a live session

​6. Add Hosted Checkout

Hosted Checkout overview

Configuration

​7. Retrieve exact SDK contracts

​Direct REST integration

​Next steps

Production storefront

Catalog

Authentication

Cart

1. Install the SDK

2. Set environment variables

3. Initialize the SDK

4. Make a public catalog request

5. Start a live session

6. Add Hosted Checkout

7. Retrieve exact SDK contracts

Direct REST integration

Next steps