Configuration

Commerce Engine uses one unified package, @commercengine/storefront, with framework-specific subpath exports. Configuration differs slightly between a browser SPA and a first-party SSR wrapper, but the architecture is the same:

public reads use a public accessor
live user flows use a session accessor
one storefront factory owns the configuration
Hosted Checkout shares the same session when both packages are installed

Core package

npm install @commercengine/storefront

Vite browser SPA configuration

Use createStorefront() for React, Vue, Svelte, Solid, or vanilla browser applications. This example uses Vite environment variables; other bundlers should supply the same values through their own public environment mechanism.

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();

Session configuration belongs under session. Do not place tokenStorage at the top level of createStorefront().

First-party SSR wrappers

Use the framework wrapper instead of configuring browser and server storage manually.

Framework	Client import	Server import
Next.js	`@commercengine/storefront/nextjs`	built into the wrapper
TanStack Start	`@commercengine/storefront/tanstack-start`	`@commercengine/storefront/tanstack-start/server`
Astro	`@commercengine/storefront/astro`	`@commercengine/storefront/astro/server`
SvelteKit	`@commercengine/storefront/sveltekit`	`@commercengine/storefront/sveltekit/server`

Example Next.js configuration:

lib/storefront.ts

import { Environment } from "@commercengine/storefront";
import { createNextjsStorefront } from "@commercengine/storefront/nextjs";

export const storefront = createNextjsStorefront({
  storeId: process.env.NEXT_PUBLIC_STORE_ID!,
  apiKey: process.env.NEXT_PUBLIC_API_KEY!,
  environment:
    process.env.NEXT_PUBLIC_CE_ENV === "production"
      ? Environment.Production
      : Environment.Staging,
  tokenStorageOptions: { prefix: "myapp_" },
});

The wrapper aligns browser and request-cookie storage automatically. Do not add BrowserTokenStorage or CookieTokenStorage to a first-party SSR wrapper.

Next.js

App Router accessors, bootstrap, Server Actions, and SSG/ISR.

TanStack Start

Client/server entry points, route loaders, and deployment adapters.

Astro

Frontmatter, request cookies, middleware, and islands.

SvelteKit

Universal loads, server loads, form actions, and hooks.

Required configuration

`storeId`

The store identifier from the Commerce Engine Admin Portal.

`apiKey`

The publishable Storefront API key. It is intended for storefront clients and is scoped by Commerce Engine. It is not an admin secret and must not be confused with private admin, webhook, or payment-provider credentials.

`environment`

Use the Environment enum rather than hardcoded strings in Storefront SDK configuration.

import { Environment } from "@commercengine/storefront";

const runtimeEnvironment = getPublicEnvironmentValue();
const environment =
  runtimeEnvironment === "production"
    ? Environment.Production
    : Environment.Staging;

Read runtimeEnvironment from the framework-specific variable shown in the environment table below. Do not copy a Vite-only import.meta.env expression into Next.js, SvelteKit, Astro, or Node.js.

Session configuration

Browser token storage

Use BrowserTokenStorage only for browser SPAs using the base createStorefront() factory.

session: {
  tokenStorage: new BrowserTokenStorage("brand_"),
}

The prefix prevents token-name collisions when multiple storefronts run on the same origin.

SSR token storage

First-party wrappers use cookie-backed storage automatically through tokenStorageOptions.

tokenStorageOptions: {
  prefix: "brand_",
  path: "/",
  sameSite: "lax",
}

For a framework without a first-party wrapper, use @commercengine/ssr-utils and a request-bound ServerTokenStorage. Do not use browser cookie storage as the server-side session layer.

Node.js storage

For a short-lived, isolated server process, use MemoryTokenStorage. For multiple concurrent end users, create a request- or user-bound session instance rather than sharing one mutable token store globally. See Node.js for the request-isolation pattern.

Public versus session accessors

// No live user session; safe for public browsing and build-time reads
const publicSdk = storefront.public();

// Anonymous or logged-in session; cart, auth, account, orders, payments
const sdk = storefront.session();

For SSR wrappers, use publicStorefront(), clientStorefront(), and the framework’s server accessor. Never use a session accessor in build-time or prerender code.

Default headers

Use defaultHeaders for store-wide request context such as B2B customer-group pricing.

export const storefront = createStorefront({
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  defaultHeaders: {
    customer_group_id: "customer-group-id",
  },
  session: {
    tokenStorage: new BrowserTokenStorage("brand_"),
  },
});

Only set a customer group after the application has authoritative group information. Do not guess or derive group IDs from display labels.

Hosted Checkout configuration

When the application uses both @commercengine/storefront and @commercengine/checkout, the Storefront SDK is the single session owner. Checkout must use authMode: "provided" and tokens must synchronize in both directions. For a browser SPA, the SDK-to-checkout callback belongs inside session:

import { getCheckout } from "@commercengine/checkout";

export const storefront = createStorefront({
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  session: {
    tokenStorage: new BrowserTokenStorage("brand_"),
    onTokensUpdated: (accessToken, refreshToken) => {
      getCheckout().updateTokens(accessToken, refreshToken);
    },
  },
});

The exported checkout store safely ignores an SDK token callback that occurs before initCheckout() creates the underlying iframe instance. Pass the current token pair into initCheckout() for initial hydration; later token updates are forwarded through this callback. For Next.js, TanStack Start, Astro, and SvelteKit wrappers, onTokensUpdated is a top-level wrapper option. Follow the framework-specific guide rather than moving the SPA configuration unchanged.

Environment-variable conventions

Runtime	Store ID	API key	Environment
Vite / TanStack Start	`VITE_STORE_ID`	`VITE_API_KEY`	`VITE_CE_ENV`
Next.js	`NEXT_PUBLIC_STORE_ID`	`NEXT_PUBLIC_API_KEY`	`NEXT_PUBLIC_CE_ENV`
Astro / SvelteKit	`PUBLIC_STORE_ID`	`PUBLIC_API_KEY`	`PUBLIC_CE_ENV`
Node.js	`CE_STORE_ID`	`CE_API_KEY`	`CE_ENV`

Commit an .env.example containing placeholder values, never real credentials.

Configuration checklist

[ ] unified @commercengine/storefront package installed
[ ] framework-specific factory selected
[ ] one shared storefront configuration
[ ] correct public environment-variable prefix
[ ] public and session accessors used in the right contexts
[ ] root bootstrap mounted for first-party SSR wrappers
[ ] no browser storage used as request-bound server storage
[ ] Hosted Checkout uses provided mode when Storefront SDK is present
[ ] token sync wired in both directions
[ ] production build passes on the target deployment runtime

Exact SDK reference

Retrieve the current SDK surface and type definitions from the LLM-first reference. Use .md URLs or Accept: text/markdown for agent workflows.

Getting Started

Core Features

Framework Integration

Advanced Usage

Core package

Vite browser SPA configuration

First-party SSR wrappers

Next.js

TanStack Start

Astro

SvelteKit

Required configuration

`storeId`

`apiKey`

`environment`

Session configuration

Browser token storage

SSR token storage

Node.js storage

Public versus session accessors

Default headers

Hosted Checkout configuration

Environment-variable conventions

Configuration checklist

Exact SDK reference

​Core package

​Vite browser SPA configuration

​First-party SSR wrappers

Next.js

TanStack Start

Astro

SvelteKit

​Required configuration

​storeId

​apiKey

​environment

​Session configuration

​Browser token storage

​SSR token storage

​Node.js storage

​Public versus session accessors

​Default headers

​Hosted Checkout configuration

​Environment-variable conventions

​Configuration checklist

Exact SDK reference

Core package

Vite browser SPA configuration

First-party SSR wrappers

Required configuration

`storeId`

`apiKey`

`environment`

Session configuration

Browser token storage

SSR token storage

Node.js storage

Public versus session accessors

Default headers

Hosted Checkout configuration

Environment-variable conventions

Configuration checklist