Setting Up Commerce Engine

ce-setup

Set up the Commerce Engine TypeScript SDK in any project. Framework detection, public vs session client selection, token storage choices, environment variables, and migration guidance.

commercengine/skills·0installs0stars

SKILL.md

Full skill instructions

LLM Docs Header: All requests to https://llm-docs.commercengine.io must include the Accept: text/markdown header (or append .md to the URL path). Without it, responses return HTML instead of parseable markdown.

Setting Up Commerce Engine

This skill sets up the latest Commerce Engine SDK surface.

Current Mental Model

All frameworks install @commercengine/storefront — a unified package with subpath exports:

SPA: import { createStorefront } from "@commercengine/storefront" → storefront.public() / storefront.session()
Next.js: import { createNextjsStorefront } from "@commercengine/storefront/nextjs" → storefront.publicStorefront() / storefront.clientStorefront() / await storefront.serverStorefront()
TanStack Start: import { createTanStackStartStorefront } from "@commercengine/storefront/tanstack-start" → storefront.publicStorefront() / storefront.clientStorefront() + separate server entry for serverStorefront()
Astro: import { createAstroStorefront } from "@commercengine/storefront/astro" → storefront.publicStorefront() / storefront.clientStorefront() + separate server entry for serverStorefront(cookies)
SvelteKit: import { createSvelteKitStorefront } from "@commercengine/storefront/sveltekit" → storefront.publicStorefront() / storefront.clientStorefront() + separate server entry for serverStorefront(cookies)

The @commercengine/storefront-sdk-nextjs package is deprecated. Use @commercengine/storefront/nextjs instead.

Quick Reference

Step	Action
1. Detect framework	Check `package.json` and config files
2. Install SDK	`@commercengine/storefront` (all frameworks)
3. Initialize storefront	SPA: `createStorefront(...)`, Next.js: `createNextjsStorefront(...)`, TanStack Start: `createTanStackStartStorefront(...)`, Astro: `createAstroStorefront(...)`, SvelteKit: `createSvelteKitStorefront(...)`
4. Set env vars	Next.js: `NEXT_PUBLIC_`, TanStack Start / SPA: `VITE_`, Astro / SvelteKit: `PUBLIC_*`
5. Bootstrap session	SPA: call `sdk.ensureAccessToken()` once during startup if you want eager session setup, SSR frameworks: `storefront.bootstrap()` in a client component
6. Use the right accessor	Public reads: `publicStorefront()` / `public()`, Session flows: `clientStorefront()` / `serverStorefront()` / `session()`
7. Hosted Checkout (if used)	Required: `authMode: "provided"` with two-way token sync (any app using the Storefront SDK)

Canonical Setup (Storefront + Hosted Checkout)

If the app uses Hosted Checkout alongside the Storefront SDK, authMode: "provided" with two-way token sync is required — not optional. The SDK manages its own session for API calls; without provided mode, checkout creates a second independent session. This is the canonical setup:

The Storefront SDK owns session state.
Hosted Checkout runs in authMode: "provided".
Initialize checkout once at app startup, not per route or component render.
Token sync is mandatory in both directions:
- SDK -> checkout via updateTokens(...)
- checkout -> SDK via onTokensUpdated

import {
  BrowserTokenStorage,
  createStorefront,
} from "@commercengine/storefront";
import { getCheckout, initCheckout } from "@commercengine/checkout";

const tokenStorage = new BrowserTokenStorage("myapp_");

export const storefront = createStorefront({
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  session: {
    tokenStorage,
    // Note: in SPA (createStorefront), onTokensUpdated is nested inside `session`.
    // In SSR wrappers (createNextjsStorefront / createTanStackStartStorefront),
    // it is a top-level config property — do not nest it under `session` there.
    onTokensUpdated: (accessToken, refreshToken) => {
      getCheckout().updateTokens(accessToken, refreshToken);
    },
  },
});

const sessionSdk = storefront.session();
const accessToken = await sessionSdk.ensureAccessToken();
const refreshToken = await tokenStorage.getRefreshToken();

initCheckout({
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  authMode: "provided",
  accessToken: accessToken ?? undefined,
  refreshToken: refreshToken ?? undefined,
  onTokensUpdated: ({ accessToken, refreshToken }) => {
    void sessionSdk.setTokens(accessToken, refreshToken);
  },
});

Framework Detection

Check package.json and config files to identify the framework:

Indicator	Framework	Import Path	Session Storage
`next` in deps + `next.config.*`	Next.js	`@commercengine/storefront/nextjs`	Built-in (cookie-backed)
`@tanstack/react-start` in deps	TanStack Start	`@commercengine/storefront/tanstack-start`	Built-in (cookie-backed)
`astro` in deps	Astro	`@commercengine/storefront/astro`	Built-in (cookie-backed)
`@sveltejs/kit` in deps	SvelteKit	`@commercengine/storefront/sveltekit`	Built-in (cookie-backed)
`nuxt` in deps	Nuxt	`@commercengine/storefront` + `@commercengine/ssr-utils`	`ServerTokenStorage`
`vite.config.*` + browser app	React / Vue / Svelte / Solid SPA	`@commercengine/storefront`	`BrowserTokenStorage`
`express` in deps	Express / Node.js	`@commercengine/storefront`	`MemoryTokenStorage` or custom `TokenStorage`
None of above	Vanilla JS	`@commercengine/storefront`	`BrowserTokenStorage`

Decision Tree

User Request: "Set up Commerce Engine" / "Add e-commerce"
    │
    ├─ Read package.json + config files
    │
    ├─ Next.js detected?
    │   ├─ YES → Install @commercengine/storefront
    │   │        → Use createNextjsStorefront() from @commercengine/storefront/nextjs
    │   │        → Root layout uses storefront.publicStorefront() + StorefrontBootstrap
    │   │        → See ce-ssr-patterns for request-bound usage
    │   └─ NO ↓
    │
    ├─ TanStack Start detected?
    │   ├─ YES → Install @commercengine/storefront
    │   │        → Use createTanStackStartStorefront() from @commercengine/storefront/tanstack-start
    │   │        → Server-only: createTanStackStartServerStorefront() from .../tanstack-start/server
    │   └─ NO ↓
    │
    ├─ Astro detected?
    │   ├─ YES → Install @commercengine/storefront
    │   │        → Use createAstroStorefront() from @commercengine/storefront/astro
    │   │        → Server-only: createAstroServerStorefront() from .../astro/server
    │   └─ NO ↓
    │
    ├─ SvelteKit detected?
    │   ├─ YES → Install @commercengine/storefront
    │   │        → Use createSvelteKitStorefront() from @commercengine/storefront/sveltekit
    │   │        → Server-only: createSvelteKitServerStorefront() from .../sveltekit/server
    │   └─ NO ↓
    │
    ├─ Other SSR framework (Nuxt)?
    │   ├─ YES → Install @commercengine/storefront + @commercengine/ssr-utils
    │   │        → Use ServerTokenStorage with CookieAdapter
    │   └─ NO  → Install @commercengine/storefront
    │            → Use BrowserTokenStorage (SPA) or MemoryTokenStorage (Node)
    │
    ├─ Using Hosted Checkout?
    │   ├─ YES → Install @commercengine/checkout
    │   │        → authMode: "provided"
    │   │        → Two-way token sync (SDK ↔ checkout)
    │   └─ NO → SDK-only setup
    │
    └─ Create one storefront factory and use the framework-appropriate accessors

Setup by Framework

Next.js (App Router)

npm install @commercengine/storefront

// 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: Environment.Staging,
  tokenStorageOptions: { prefix: "myapp_" },
});

// components/storefront-bootstrap.tsx
"use client";

import { useEffect } from "react";
import { storefront } from "@/lib/storefront";

export function StorefrontBootstrap() {
  useEffect(() => {
    storefront.bootstrap().catch(console.error);
  }, []);
  return null;
}

The root layout is a Server Component, but it can render StorefrontBootstrap (a Client Component) as a child — this is standard Next.js composition. Place the bootstrap component as high in the tree as possible.

// app/layout.tsx (Server Component — this is fine)
import { storefront } from "@/lib/storefront";
import { StorefrontBootstrap } from "@/components/storefront-bootstrap";

const { data: storeConfig } = await storefront.publicStorefront().store.getStoreConfig();

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <StorefrontBootstrap />
        <header>{storeConfig?.store_config?.brand.name}</header>
        {children}
      </body>
    </html>
  );
}

For the full Next.js request model, see ce-ssr-patterns.

Using Hosted Checkout? See ce-cart-checkout and references/hosted-checkout.md for the token sync pattern.

# .env.local
NEXT_PUBLIC_STORE_ID=your-store-id
NEXT_PUBLIC_API_KEY=your-api-key

TanStack Start

npm install @commercengine/storefront

// lib/storefront.ts
import { Environment } from "@commercengine/storefront";
import { createTanStackStartStorefront } from "@commercengine/storefront/tanstack-start";

export const storefrontConfig = {
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  environment: Environment.Staging,
  tokenStorageOptions: { prefix: "myapp_" },
};

export const storefront = createTanStackStartStorefront(storefrontConfig);

// lib/storefront.server.ts (server-only module)
import { createTanStackStartServerStorefront } from "@commercengine/storefront/tanstack-start/server";
import { storefrontConfig } from "./storefront";

const serverStorefrontFactory = createTanStackStartServerStorefront(storefrontConfig);

export function serverStorefront() {
  return serverStorefrontFactory.serverStorefront();
}

// components/storefront-bootstrap.tsx
import { useEffect } from "react";
import { storefront } from "@/lib/storefront";

export function StorefrontBootstrap() {
  useEffect(() => {
    storefront.bootstrap().catch(console.error);
  }, []);
  return null;
}

Mount StorefrontBootstrap in the root layout (__root.tsx).

# .env
VITE_STORE_ID=your-store-id
VITE_API_KEY=your-api-key

Astro

npm install @commercengine/storefront

// src/lib/storefront-config.ts
import { Environment } from "@commercengine/storefront";
import type { AstroStorefrontConfig } from "@commercengine/storefront/astro";

export const storefrontConfig: AstroStorefrontConfig = {
  storeId: import.meta.env.PUBLIC_STORE_ID,
  apiKey: import.meta.env.PUBLIC_API_KEY,
  environment: Environment.Staging,
  tokenStorageOptions: { prefix: "myapp_" },
};

// src/lib/storefront.ts
import { createAstroStorefront } from "@commercengine/storefront/astro";
import { storefrontConfig } from "./storefront-config";

export const storefront = createAstroStorefront(storefrontConfig);

// src/lib/server-storefront.ts (server-only)
import { createAstroServerStorefront } from "@commercengine/storefront/astro/server";
import { storefrontConfig } from "./storefront-config";

export const serverStorefront = createAstroServerStorefront(storefrontConfig);

Bootstrap in a root layout script, then use serverStorefront.serverStorefront(Astro.cookies) in SSR pages/API routes.

For the full Astro request model, see ce-ssr-patterns.

# .env
PUBLIC_STORE_ID=your-store-id
PUBLIC_API_KEY=your-api-key

SvelteKit

npm install @commercengine/storefront

// src/lib/storefront-config.ts
import { Environment } from "@commercengine/storefront";
import type { SvelteKitStorefrontConfig } from "@commercengine/storefront/sveltekit";
import { env } from "$env/static/public";

export const storefrontConfig: SvelteKitStorefrontConfig = {
  storeId: env.PUBLIC_STORE_ID,
  apiKey: env.PUBLIC_API_KEY,
  environment: Environment.Staging,
  tokenStorageOptions: { prefix: "myapp_" },
};

// src/lib/storefront.ts
import { createSvelteKitStorefront } from "@commercengine/storefront/sveltekit";
import { storefrontConfig } from "./storefront-config";

export const storefront = createSvelteKitStorefront(storefrontConfig);

// src/lib/server/storefront.ts (server-only — $lib/server/ is enforced by SvelteKit)
import { createSvelteKitServerStorefront } from "@commercengine/storefront/sveltekit/server";
import { storefrontConfig } from "$lib/storefront-config";

export const serverStorefront = createSvelteKitServerStorefront(storefrontConfig);

Bootstrap in root +layout.svelte via onMount, then use serverStorefront.serverStorefront(cookies) in server load functions, hooks, and actions.

For the full SvelteKit request model, see ce-ssr-patterns.

# .env
PUBLIC_STORE_ID=your-store-id
PUBLIC_API_KEY=your-api-key

React / Vue / Svelte / Solid (SPA)

npm install @commercengine/storefront

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

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

// Public reads
const { data: products } = await storefront.public().catalog.listProducts();

// Live session flows
const sessionSdk = storefront.session();
await sessionSdk.ensureAccessToken();

# .env
VITE_STORE_ID=your-store-id
VITE_API_KEY=your-api-key

Node.js / Express

npm install @commercengine/storefront

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

export const storefront = createStorefront({
  storeId: process.env.CE_STORE_ID!,
  environment: process.env.NODE_ENV === "production" ? Environment.Production : Environment.Staging,
  apiKey: process.env.CE_API_KEY!,
  session: {
    tokenStorage: new MemoryTokenStorage(),
  },
});

Session Storage Guide

Storage	Use Case	Persistence	SSR Safe
`BrowserTokenStorage`	Browser SPAs	`localStorage`	No
`CookieTokenStorage`	Browser cookies / cross-tab cookie sync	Cookies	Browser only
`MemoryTokenStorage`	Server-side or temporary storage	In-memory	Yes
`ServerTokenStorage`	SSR frameworks with request cookies	Cookies via framework adapter	Yes

Use ServerTokenStorage from @commercengine/ssr-utils for live SSR request flows. Do not use CookieTokenStorage as the primary SSR server storage layer.

First API Call

Public reads can run immediately:

const { data: products } = await storefront.public().catalog.listProducts();

If the app wants an eager live anonymous/logged-in session, do it once during startup:

const sessionSdk = storefront.session();
await sessionSdk.ensureAccessToken();
const { data: wishlist } = await sessionSdk.cart.getWishlist();

Ordinary session-aware SDK methods such as sdk.cart.getWishlist(), sdk.cart.addToWishlist(), sdk.cart.getUserCart(), and sdk.customer.listAddresses() do not require a manual ensureAccessToken() call. The middleware and overloads handle session creation and ID resolution automatically. If your app wants eager bootstrap, call it once during startup instead of scattering ensureAccessToken() through feature code.

Session Helpers

Most session SDK methods that need a user_id or customer_id have parameterless overloads that auto-resolve from the current session. You do not need to manually fetch IDs and pass them. For example:

// Preferred — SDK auto-resolves user_id from session
const { data } = await sdk.cart.getUserCart();
const { data: wishlist } = await sdk.cart.getWishlist();
const { data: orders } = await sdk.order.listOrders();
const { data: addresses } = await sdk.customer.listAddresses();

// Only pass IDs explicitly when operating on behalf of a different user (admin scenarios)
const { data } = await sdk.cart.getUserCart({ user_id: "other_user_id" });

Methods with parameterless overloads (auto-resolve user_id or customer_id):

Cart: getUserCart(), deleteUserCart(), getWishlist(), addToWishlist(), removeFromWishlist()
Orders: listOrders()
Customer: listAddresses(), createAddress(), getAddress(), updateAddress(), deleteAddress(), getLoyaltyDetails(), listLoyaltyPointsActivity(), listCustomerReviews(), listSavedPaymentMethods(), listCustomerCards()

Auth client methods still require explicit IDs — getUserDetails({ id }), updateUserDetails({ id }), etc. Use sdk.getUserId() to get the current user's ID for these calls.

When You Still Need Session Helpers

Helper	When to Use
`ensureAccessToken()`	Call once during startup when you explicitly want to establish the session early
`getAccessToken()`	Read current token passively (passing to Hosted Checkout init)
`sdk.session.peekRefreshToken()`	Read current refresh token passively (passing to Hosted Checkout init)
`setTokens(accessToken, refreshToken?)`	Sync tokens from Hosted Checkout back into the SDK
`getUserId()`	Pass to auth client methods that require explicit `{ id }`
`getUserInfo()`	Read user info for UI display (name, email) without an API call — decoded from JWT
`isLoggedIn()` / `isAnonymous()`	Conditional UI rendering (show login button vs account menu)

`sdk.session` — Peek vs Ensure

The session property offers fine-grained access with two modes:

Peek — passive read, never creates sessions or refreshes tokens, returns null on failure:

sdk.session.peekAccessToken() / peekRefreshToken() / peekUserInfo() / peekUserId() / peekCustomerId()

Ensure — may create an anonymous session or refresh expired tokens, throws on failure:

sdk.session.ensureAccessToken() / ensureUserInfo() / ensureUserId() / ensureCustomerId()

Use peek when you want current state without side effects (e.g., passing tokens to Hosted Checkout init). Use ensure when you explicitly need a valid token or identity before any other session call. Most cart/order/customer methods already manage this internally.

Environment Variables

Variable	Required	Description
`CE_STORE_ID` / `NEXT_PUBLIC_STORE_ID`	Yes	Your store identifier
`CE_API_KEY` / `NEXT_PUBLIC_API_KEY`	Yes	Storefront API key
`CE_ENVIRONMENT` / `NEXT_PUBLIC_ENVIRONMENT`	No	`staging` or `production`

Default Headers

The SDK supports defaultHeaders in the config. This is useful for B2B storefronts with customer groups where pricing and promotions vary by group.

const storefront = createStorefront({
  storeId: "...",
  apiKey: "...",
  defaultHeaders: {
    customer_group_id: "01JHS28V83KDWTRBXXJQRTEKA0",
  },
  session: {
    tokenStorage: new BrowserTokenStorage("myapp_"),
  },
});

Set customer_group_id after login from the user profile or auth response. Relevant catalog methods automatically receive it.

Analytics

Analytics are server-side and automated. Commerce Engine collects e-commerce events per the Segment spec. Merchants route these events into Segment, Rudderstack, or similar tools via Admin integrations. Storefront code does not need to wire analytics manually.

Common Pitfalls

Level	Issue	Solution
HIGH	Using `public()` for cart/auth/customer/order flows	Use `session()` for any live user or anonymous session work
HIGH	Using `CookieTokenStorage` as SSR server storage	Use `ServerTokenStorage` from `@commercengine/ssr-utils`, or use the built-in wrappers for Next.js / TanStack Start
HIGH	Skipping `StorefrontBootstrap` in SSR apps	Mount a client component calling `storefront.bootstrap()` once in the root layout
HIGH	Using deprecated `@commercengine/storefront-sdk-nextjs`	Migrate to `@commercengine/storefront/nextjs` with `createNextjsStorefront()`
MEDIUM	Bootstrapping anonymous auth in build/prerender code	Use `public()` instead
MEDIUM	Duplicating config across public and session clients	Prefer one `createStorefront(...)` factory

Documentation

Core SDK: https://www.commercengine.io/docs/sdk
Next.js Integration: https://www.commercengine.io/docs/sdk/nextjs-integration
LLM Reference: https://llm-docs.commercengine.io/sdk/

Setting Up Commerce Engine

SKILL.md

Setting Up Commerce Engine

Current Mental Model

Quick Reference

Canonical Setup (Storefront + Hosted Checkout)

Framework Detection

Decision Tree

Setup by Framework

Next.js (App Router)

TanStack Start

Astro

SvelteKit

React / Vue / Svelte / Solid (SPA)

Node.js / Express

Session Storage Guide

First API Call

Session Helpers

When You Still Need Session Helpers

sdk.session — Peek vs Ensure

Environment Variables

Default Headers

Analytics

Common Pitfalls

See Also

Documentation

`sdk.session` — Peek vs Ensure