ce-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

LLM文档头部说明：所有发往
https://llm-docs.commercengine.io
的请求必须携带
Accept: text/markdown
请求头（或者在URL路径后追加
.md
）。否则响应会返回HTML而非可解析的markdown格式。

Setting Up Commerce Engine

Commerce Engine配置指南

This skill sets up the Commerce Engine TypeScript SDK for your project.

本指南用于为你的项目配置Commerce Engine TypeScript SDK。

Quick Reference

快速参考

Step	Action
1. Detect framework	Check `package.json` and config files
2. Install SDKs	`@commercengine/storefront-sdk` (+ `@commercengine/checkout` if using Hosted Checkout)
3. Choose token storage	`BrowserTokenStorage` (SPA), `CookieTokenStorage` (SSR), `MemoryTokenStorage` (Node.js)
4. Set env vars	`CE_STORE_ID` and `CE_API_KEY`
5. Initialize SDK	Create `lib/storefront.ts`
6. Get anonymous token	`sdk.auth.getAnonymousToken()` before any API call
7. Hosted Checkout (if used)	Initialize checkout with `authMode: "provided"` and two-way token sync

步骤	操作
1. 检测框架	检查 `package.json` 和配置文件
2. 安装SDK	`@commercengine/storefront-sdk` （如果使用托管结账功能，额外安装 `@commercengine/checkout` ）
3. 选择令牌存储方案	`BrowserTokenStorage` （单页应用）、 `CookieTokenStorage` （服务端渲染项目）、 `MemoryTokenStorage` （Node.js项目）
4. 配置环境变量	`CE_STORE_ID` 和 `CE_API_KEY`
5. 初始化SDK	创建 `lib/storefront.ts` 文件
6. 获取匿名令牌	发起任何API调用前先调用 `sdk.auth.getAnonymousToken()`
7. 托管结账配置（如果使用）	以 `authMode: "provided"` 初始化结账模块并配置双向令牌同步

Canonical Setup (Storefront + Hosted Checkout)

标准配置方案（门店前端 + 托管结账）

If the storefront uses Hosted Checkout, this is the canonical setup:

Storefront SDK is token owner (creation, refresh, storage).
Hosted Checkout runs in
authMode: "provided"
.
Initialize checkout exactly once at app startup (root app entry/bootstrap), not per route or per component render.
Two-way sync is mandatory:
- SDK -> checkout via
```
updateTokens(...)
```
- checkout -> SDK via
```
onTokensUpdated
```

typescript

import StorefrontSDK, { BrowserTokenStorage } from "@commercengine/storefront-sdk";
import { initCheckout, getCheckout } from "@commercengine/checkout";

const tokenStorage = new BrowserTokenStorage("myapp_");

export const storefront = new StorefrontSDK({
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  tokenStorage,
  onTokensUpdated: (accessToken, refreshToken) => {
    // SDK -> checkout
    getCheckout().updateTokens(accessToken, refreshToken);
  },
});

const accessToken = await tokenStorage.getAccessToken();
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 }) => {
    // checkout -> SDK
    storefront.setTokens(accessToken, refreshToken);
  },
});

如果你的门店前端使用托管结账功能，请遵循以下标准配置方案：

门店前端SDK作为令牌持有者（负责令牌的创建、刷新、存储）。
托管结账以
authMode: "provided"
模式运行。
仅在应用启动时初始化一次结账模块（在应用根入口/启动文件中初始化），不要在每个路由或组件渲染时重复初始化。
必须配置双向令牌同步：
- SDK通过
```
updateTokens(...)
```
  向结账模块同步令牌
- 结账模块通过
```
onTokensUpdated
```
  向SDK同步令牌

typescript

import StorefrontSDK, { BrowserTokenStorage } from "@commercengine/storefront-sdk";
import { initCheckout, getCheckout } from "@commercengine/checkout";

const tokenStorage = new BrowserTokenStorage("myapp_");

export const storefront = new StorefrontSDK({
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  tokenStorage,
  onTokensUpdated: (accessToken, refreshToken) => {
    // SDK -> 结账模块同步
    getCheckout().updateTokens(accessToken, refreshToken);
  },
});

const accessToken = await tokenStorage.getAccessToken();
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 }) => {
    // 结账模块 -> SDK同步
    storefront.setTokens(accessToken, refreshToken);
  },
});

Framework Detection

框架检测

Check

package.json

and config files to identify the framework:

Indicator	Framework	SDK Package	Token Storage
`next` in deps + `next.config.*`	Next.js	`@commercengine/storefront-sdk-nextjs`	`CookieTokenStorage`
`vite.config.ts` + `@vitejs/plugin-react`	React SPA	`@commercengine/storefront-sdk`	`BrowserTokenStorage`
`vite.config.ts` + `@vitejs/plugin-vue`	Vue SPA	`@commercengine/storefront-sdk`	`BrowserTokenStorage`
`svelte.config.js`	Svelte/SvelteKit	`@commercengine/storefront-sdk`	`BrowserTokenStorage`
`solid-js` in deps	Solid	`@commercengine/storefront-sdk`	`BrowserTokenStorage`
`express` in deps	Express/Node.js	`@commercengine/storefront-sdk`	`MemoryTokenStorage`
None of above	Vanilla JS	`@commercengine/storefront-sdk`	`BrowserTokenStorage`

检查

package.json

和配置文件来识别项目使用的框架：

识别标识	框架	SDK包	令牌存储方案
依赖中包含 `next` + 存在 `next.config.*` 文件	Next.js	`@commercengine/storefront-sdk-nextjs`	`CookieTokenStorage`
存在 `vite.config.ts` + 依赖包含 `@vitejs/plugin-react`	React 单页应用	`@commercengine/storefront-sdk`	`BrowserTokenStorage`
存在 `vite.config.ts` + 依赖包含 `@vitejs/plugin-vue`	Vue 单页应用	`@commercengine/storefront-sdk`	`BrowserTokenStorage`
存在 `svelte.config.js`	Svelte/SvelteKit	`@commercengine/storefront-sdk`	`BrowserTokenStorage`
依赖中包含 `solid-js`	Solid	`@commercengine/storefront-sdk`	`BrowserTokenStorage`
依赖中包含 `express`	Express/Node.js	`@commercengine/storefront-sdk`	`MemoryTokenStorage`
不符合以上所有条件	原生JS	`@commercengine/storefront-sdk`	`BrowserTokenStorage`

Decision Tree

决策树

User Request: "Set up Commerce Engine" / "Add e-commerce"
    │
    ├─ Read package.json + config files
    │
    ├─ Next.js detected?
    │   ├─ YES → Install @commercengine/storefront-sdk-nextjs
    │   │        → Root layout: storefront({ isRootLayout: true }) + StorefrontSDKInitializer
    │   │        → See ce-nextjs-patterns for advanced usage
    │   └─ NO → Install @commercengine/storefront-sdk
    │
    ├─ Choose token storage based on framework
    │
    ├─ Using Hosted Checkout?
    │   ├─ YES → Install @commercengine/checkout
    │   │        → Initialize checkout with authMode: "provided"
    │   │        → Wire two-way token sync (SDK ↔ checkout)
    │   └─ NO → SDK-only setup
    │
    ├─ Set environment variables
    │
    └─ Initialize SDK + get anonymous token

用户请求: "配置Commerce Engine" / "添加电商功能"
    │
    ├─ 读取package.json + 配置文件
    │
    ├─ 检测到Next.js？
    │   ├─ 是 → 安装@commercengine/storefront-sdk-nextjs
    │   │        → 根布局文件: 调用storefront({ isRootLayout: true }) + 引入StorefrontSDKInitializer
    │   │        → 进阶用法参考ce-nextjs-patterns
    │   └─ 否 → 安装@commercengine/storefront-sdk
    │
    ├─ 根据框架选择令牌存储方案
    │
    ├─ 是否使用托管结账？
    │   ├─ 是 → 安装@commercengine/checkout
    │   │        → 以authMode: "provided"初始化结账模块
    │   │        → 配置双向令牌同步（SDK ↔ 结账模块）
    │   └─ 否 → 仅配置SDK即可
    │
    ├─ 配置环境变量
    │
    └─ 初始化SDK + 获取匿名令牌

Setup by Framework

按框架配置

Next.js (App Router)

bash

npm install @commercengine/storefront-sdk-nextjs

typescript

// lib/storefront.ts
export { storefront } from "@commercengine/storefront-sdk-nextjs";

tsx

// app/layout.tsx
import { StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
import { storefront } from "@/lib/storefront";

// Root Layout has no request context — use isRootLayout flag
const sdk = storefront({ isRootLayout: true });

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <StorefrontSDKInitializer />
        {children}
      </body>
    </html>
  );
}

For the full
storefront()
mental model (server components, client components, server actions, SSG), see
ce-nextjs-patterns
.
Using Hosted Checkout? Replace the simple re-export in
lib/storefront.ts
with
createStorefront()
to wire two-way token sync. See
ce-cart-checkout
→
references/hosted-checkout.md
§ "Next.js".

env

undefined

bash

npm install @commercengine/storefront-sdk-nextjs

typescript

// lib/storefront.ts
export { storefront } from "@commercengine/storefront-sdk-nextjs";

tsx

// app/layout.tsx
import { StorefrontSDKInitializer } from "@commercengine/storefront-sdk-nextjs/client";
import { storefront } from "@/lib/storefront";

// 根布局没有请求上下文 — 使用isRootLayout参数
const sdk = storefront({ isRootLayout: true });

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <StorefrontSDKInitializer />
        {children}
      </body>
    </html>
  );
}

如需了解完整的
storefront()
设计逻辑（服务端组件、客户端组件、服务端操作、静态站点生成），请查看
ce-nextjs-patterns
。
使用托管结账？ 将
lib/storefront.ts
中的简单导出替换为
createStorefront()
来配置双向令牌同步，参考
ce-cart-checkout
→
references/hosted-checkout.md
§ "Next.js"章节。

env

undefined

.env.local

NEXT_PUBLIC_STORE_ID=your-store-id NEXT_PUBLIC_API_KEY=your-api-key

undefined

NEXT_PUBLIC_STORE_ID=your-store-id NEXT_PUBLIC_API_KEY=your-api-key

undefined

React / Vue / Svelte / Solid (SPA)

React / Vue / Svelte / Solid (单页应用)

bash

npm install @commercengine/storefront-sdk

typescript

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

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

env

undefined

bash

npm install @commercengine/storefront-sdk

typescript

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

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

env

undefined

.env

VITE_STORE_ID=your-store-id VITE_API_KEY=your-api-key

undefined

VITE_STORE_ID=your-store-id VITE_API_KEY=your-api-key

undefined

Node.js / Express

bash

npm install @commercengine/storefront-sdk

typescript

// src/lib/storefront.ts
import StorefrontSDK, { Environment, MemoryTokenStorage } from "@commercengine/storefront-sdk";

const sdk = new StorefrontSDK({
  storeId: process.env.CE_STORE_ID!,
  environment: process.env.NODE_ENV === "production" ? Environment.Production : Environment.Staging,
  apiKey: process.env.CE_API_KEY!,
  tokenStorage: new MemoryTokenStorage(),
  timeout: 30000,
});

export default sdk;

bash

npm install @commercengine/storefront-sdk

typescript

// src/lib/storefront.ts
import StorefrontSDK, { Environment, MemoryTokenStorage } from "@commercengine/storefront-sdk";

const sdk = new StorefrontSDK({
  storeId: process.env.CE_STORE_ID!,
  environment: process.env.NODE_ENV === "production" ? Environment.Production : Environment.Staging,
  apiKey: process.env.CE_API_KEY!,
  tokenStorage: new MemoryTokenStorage(),
  timeout: 30000,
});

export default sdk;

Token Storage Guide

令牌存储指南

Storage	Use Case	Persistence	SSR Safe
`BrowserTokenStorage`	SPAs (React, Vue, Svelte, Solid)	localStorage	No
`CookieTokenStorage`	SSR frameworks (Next.js)	Cookies	Yes
`MemoryTokenStorage`	Server-side (Node.js, Express)	In-memory	Yes

存储方案	适用场景	持久化能力	SSR兼容
`BrowserTokenStorage`	单页应用（React、Vue、Svelte、Solid）	localStorage存储	否
`CookieTokenStorage`	SSR框架（Next.js）	Cookie存储	是
`MemoryTokenStorage`	服务端项目（Node.js、Express）	内存存储	是

First API Call

首次API调用

After setup, always authenticate anonymously before making any API calls:

typescript

// Every visitor starts as anonymous
const { data, error } = await sdk.auth.getAnonymousToken();

if (error) {
  console.error("Auth failed:", error.message);
} else {
  // Tokens are automatically managed by the SDK
  // Now you can call any API
  const { data: products } = await sdk.catalog.listProducts();
}

配置完成后，发起任何API调用前必须先进行匿名认证：

typescript

// 所有访客默认以匿名身份开始
const { data, error } = await sdk.auth.getAnonymousToken();

if (error) {
  console.error("认证失败:", error.message);
} else {
  // 令牌会由SDK自动管理
  // 现在你可以调用任何API
  const { data: products } = await sdk.catalog.listProducts();
}

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 (safe for client-side)
`NEXT_BUILD_CACHE_TOKENS`	No	Set `true` for faster Next.js builds with token caching

变量名	必填	说明
`CE_STORE_ID` / `NEXT_PUBLIC_STORE_ID`	是	你的门店ID
`CE_API_KEY` / `NEXT_PUBLIC_API_KEY`	是	门店前端API密钥（可安全用于客户端）
`NEXT_BUILD_CACHE_TOKENS`	否	设为 `true` 可通过令牌缓存加速Next.js构建

Default Headers

默认请求头

The SDK supports

defaultHeaders

in the config — headers that are automatically sent with every API call. This is useful for B2B storefronts with customer groups (retailers, stockists, distributors), where pricing and promotions vary by group.

typescript

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

Set the

customer_group_id

after the user logs in (from the user's profile or auth response). All SDK methods that support customer group pricing will automatically receive it — no need to pass it on every call. See

catalog/

§ "Customer Groups & Pricing" for what it affects.

SDK配置支持

defaultHeaders

参数，配置的请求头会自动附加到每一次API调用中。该功能适用于面向客户分层（零售商、库存商、经销商）的B2B门店前端，这类场景下定价和促销活动会随客户分组变化。

typescript

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

用户登录后可以根据用户资料或认证响应设置

customer_group_id

，所有支持客户分组定价的SDK方法会自动携带该参数，无需在每次调用时手动传入。具体影响范围请参考

catalog/

§ "客户分组与定价"章节。

Analytics

统计分析

Analytics are server-side and automated. Commerce Engine collects e-commerce events per the Segment spec. Merchants pipe these events into Segment, Rudderstack, or other tools via integrations in the Admin dashboard. Nothing needs to be done on the storefront to enable or disable analytics.

统计分析功能是服务端自动运行的。Commerce Engine会按照Segment规范收集电商事件，商家可以通过管理后台的集成功能将这些事件同步到Segment、Rudderstack或其他工具中。门店前端无需做任何配置来开启或关闭统计分析功能。

Common Pitfalls

常见问题

Level	Issue	Solution
CRITICAL	Missing anonymous auth	Must call `sdk.auth.getAnonymousToken()` before any API call
CRITICAL	App uses Storefront SDK auth + Hosted Checkout `managed` mode	Use `authMode: "provided"` and wire SDK ↔ checkout token sync
CRITICAL	Exposing admin API keys	Only storefront API keys ( `CE_API_KEY` ) are safe for client-side
HIGH	Wrong token storage for SSR	Use `CookieTokenStorage` for Next.js, not `BrowserTokenStorage`
HIGH	Missing env vars	SDK throws if `storeId` or `apiKey` is missing — check env var names
MEDIUM	Missing `StorefrontSDKInitializer`	Required in Next.js root layout for automatic anonymous auth
MEDIUM	Wrong environment	Use `Environment.Staging` for dev, `Environment.Production` for prod

严重等级	问题	解决方案
严重	缺失匿名认证	任何API调用前必须先调用 `sdk.auth.getAnonymousToken()`
严重	应用同时使用Storefront SDK认证 + 托管结账 `managed` 模式	改用 `authMode: "provided"` 并配置SDK ↔ 结账模块的双向令牌同步
严重	泄露管理员API密钥	仅门店前端API密钥（ `CE_API_KEY` ）可安全用于客户端
高	SSR项目使用了错误的令牌存储方案	Next.js项目使用 `CookieTokenStorage` ，不要用 `BrowserTokenStorage`
高	缺失环境变量	如果 `storeId` 或 `apiKey` 缺失SDK会抛出错误，请检查环境变量名称是否正确
中	缺失 `StorefrontSDKInitializer` 组件	Next.js根布局中必须引入该组件以实现自动匿名认证
中	环境配置错误	开发环境使用 `Environment.Staging` ，生产环境使用 `Environment.Production`

参考延伸

```
auth/
```
- Authentication & login flows
```
nextjs-patterns/
```
- Advanced Next.js patterns with
```
storefront()
```
```
cart-checkout/
```
- Cart management after setup

```
auth/
```
- 认证与登录流程
```
nextjs-patterns/
```
- 基于
```
storefront()
```
的进阶Next.js开发模式
```
cart-checkout/
```
- 配置完成后的购物车管理

Documentation

官方文档

SDK Installation: https://www.commercengine.io/docs/sdk/installation
Configuration: https://www.commercengine.io/docs/sdk/configuration
Token Management: https://www.commercengine.io/docs/sdk/token-management
LLM Reference: https://llm-docs.commercengine.io/sdk/

SDK安装指南: https://www.commercengine.io/docs/sdk/installation
配置说明: https://www.commercengine.io/docs/sdk/configuration
令牌管理: https://www.commercengine.io/docs/sdk/token-management
LLM参考文档: https://llm-docs.commercengine.io/sdk/

ce-setup

Original

Translation

Setting Up Commerce Engine

Commerce Engine配置指南

Quick Reference

快速参考

Canonical Setup (Storefront + Hosted Checkout)

标准配置方案（门店前端 + 托管结账）

Framework Detection

框架检测

Decision Tree

决策树

Setup by Framework

按框架配置

Next.js (App Router)

Next.js (App Router)

.env.local

.env.local

React / Vue / Svelte / Solid (SPA)

React / Vue / Svelte / Solid (单页应用)

.env

.env

Node.js / Express

Node.js / Express

Token Storage Guide

令牌存储指南

First API Call

首次API调用

Environment Variables

环境变量

Default Headers

默认请求头

Analytics

统计分析

Common Pitfalls

常见问题

See Also

参考延伸

Documentation

官方文档