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 Commerce Engine TypeScript SDK for your project.

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

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);
  },
});

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
    │   │        → 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

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

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

React / Vue / Svelte / Solid (SPA)

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

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

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;

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:

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

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.

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.

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

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/

ce-setup

NPX Install

Tags

SKILL.md Content

Setting Up Commerce Engine

Quick Reference

Canonical Setup (Storefront + Hosted Checkout)

Framework Detection

Decision Tree

Setup by Framework

Next.js (App Router)

React / Vue / Svelte / Solid (SPA)

Node.js / Express

Token Storage Guide

First API Call

Environment Variables

Default Headers

Analytics

Common Pitfalls

See Also

Documentation