陌讯skills聚合平台

ce-setup

📁 commercengine/skills 📅 6 days ago
4
总安装量
4
周安装量
#53448
全站排名
安装命令
npx skills add https://github.com/commercengine/skills --skill ce-setup

Agent 安装分布

opencode 4
gemini-cli 4
claude-code 4
github-copilot 4
codex 4
kimi-cli 4

Skill 文档

Setting Up Commerce Engine

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

Quick Reference

Step Action
1. Detect framework Check package.json and config files
2. Install SDK npm install @commercengine/storefront-sdk
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

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

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
    │   │        → Use storefront() function + StorefrontSDKInitializer
    │   │        → See ce-nextjs-patterns for advanced usage
    │   └─ NO → Install @commercengine/storefront-sdk
    │
    ├─ Choose token storage based on framework
    │
    ├─ Set environment variables
    │
    └─ Initialize SDK + get anonymous token

Setup by Framework

Next.js (App Router)

npm install @commercengine/storefront-sdk-nextjs

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

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

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

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

React / Vue / Svelte / Solid (SPA)

npm install @commercengine/storefront-sdk

// 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
VITE_STORE_ID=your-store-id
VITE_API_KEY=your-api-key

Node.js / Express

npm install @commercengine/storefront-sdk

// 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

First API Call

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

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

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

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.

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.

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.

Common Pitfalls

Level Issue Solution
CRITICAL Missing anonymous auth Must call sdk.auth.getAnonymousToken() before any API call
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

See Also

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

Documentation

GitHub 仓库 ↗ ← 返回陌讯 Skills 聚合平台
本页面由 陌讯 Skills 聚合平台 收录整理，数据定期更新。