> ## Documentation Index
> Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Complete guide to configuring the TypeScript SDK for different environments and use cases

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```typescript lib/storefront.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
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();
```

<Warning>
  Session configuration belongs under `session`. Do not place `tokenStorage` at the top level of `createStorefront()`.
</Warning>

## 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:

```typescript lib/storefront.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<CardGroup cols={2}>
  <Card title="Next.js" icon="https://svgl.app/library/nextjs_icon_dark.svg" href="/docs/sdk/nextjs-integration">
    App Router accessors, bootstrap, Server Actions, and SSG/ISR.
  </Card>

  <Card title="TanStack Start" icon="https://svgl.app/library/tanstack.svg" href="/docs/sdk/tanstack-start-integration">
    Client/server entry points, route loaders, and deployment adapters.
  </Card>

  <Card title="Astro" icon="https://svgl.app/library/astro-icon-light.svg" href="/docs/sdk/astro-integration">
    Frontmatter, request cookies, middleware, and islands.
  </Card>

  <Card title="SvelteKit" icon="https://svgl.app/library/svelte.svg" href="/docs/sdk/sveltekit-integration">
    Universal loads, server loads, form actions, and hooks.
  </Card>
</CardGroup>

## 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.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/docs/sdk/nodejs-integration) for the request-isolation pattern.

## Public versus session accessors

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// 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.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
[ ] 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
```

<Card title="Exact SDK reference" icon="robot" href="https://llm-docs.commercengine.io/sdk/storefront">
  Retrieve the current SDK surface and type definitions from the LLM-first reference. Use `.md` URLs or `Accept: text/markdown` for agent workflows.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.