ce-setup（CE 设置）

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

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:

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

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

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

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

See Also

• ssr-patterns/ - Next.js and TanStack Start publicStorefront() / clientStorefront() / serverStorefront() patterns
• ssr/ - Custom SSR bindings with @commercengine/ssr-utils (Nuxt and other unsupported frameworks)
• auth/ - Authentication flows
• cart-checkout/ - Hosted Checkout sync patterns

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/