Commercetools Storefront

commercetools Storefront (framework-agnostic)

Production patterns for commercetools storefronts — covering the full range from the shared BFF foundation to B2C and B2B surface-specific features. The patterns here are framework-neutral: each is stated as a decision plus commercetools-exact code. Your frontend framework supplies the implementation primitives (file layout, render and routing primitives, the cookie read/write binding).

Architecture assumption — a server tier exists. These patterns assume your storefront runs on a stack with a server-side tier (SSR / server components / a standalone BFF service) that can hold secrets and proxy commercetools. The BFF and secret rules below are non-negotiable and depend on this. They are designed SSR-first. For a specific framework, use its stack adapter under references/stack/ — e.g. the Next.js stack — which maps each concept here to that framework's primitives and owns all file-layout and render-primitive details.

Reference implementation. Where a code example shows a file path or a render primitive, it uses the Next.js App Router as the reference implementation. The framework-neutral rule is always in the surrounding prose; the adapter pins the exact primitive.

Path & state conventions.

Each reference implementation follows these conventions for paths and state management. The conventions are not technically required, but they are widely used in production storefronts and make it easier to navigate the codebase and onboard new developers. Find the concept-mapping.md in your stack adapter for the exact primitives used.

Convention	Meaning
<server>/	Your server-side code root; each stack pins the actual directory (Example Next.js: lib/)
<api>/	the client-facing API surface the browser calls and routes
<server>/ct/*	The commercetools helper modules
<server>/ct/client	The apiRoot singleton
<server>/types	The app type-mapping root (the boundary types)
<server>/mappers/	The commercetools→app mappers
Client state	Your framework's client-side state-management / cache layer (the specific library is a stack choice) — use it for mutable per-user data

Workflow

When this skill is invoked, always follow these steps:

1. Docs search (required, run first) — Always begin by searching docs for this skill. This is the mandatory grounding step: it gathers the latest verified documentation as context for you (the agent). Do not skip it, and do not replace it with another tool (such as an MCP documentation-search tool) This script optimizes for tuned search results — run this command:

   node scripts/docs-search.mjs \
     --query "<extract key terms from user's question>" \
     --app-name "<current-app ex: claude, copilot, codex>" \
     --model "<current-model>" \
     --skill-name "commercetools-storefront" \
     --limit 10
   

   Use its output as your primary grounding. You may additionally use other tools (such as the commercetools documentation MCP) for deeper, follow-up search.

2. Combine with skill references — Cross-reference the analysis output with local references in ./references/ for complete context.

3. Provide implementation guidance — Synthesize the documentation with the specific integration mode the user is targeting.

Optional scripts

Fetch GraphQL schema — Run this when you need context about a commercetools GraphQL query or mutation — for example, to inspect a resource's fields, types, and available operations before writing a query, or to verify a GraphQL query/mutation you have just generated against the real schema. It fetches the partial GraphQL SDL for a single commercetools resource:

node scripts/graphql-schemata.mjs \
  --resource-name "<commercetools resource, e.g. Cart, Product, Order>" \
  --app-name "<current-app, e.g. claude, copilot, cursor, codex>" \
  --model "<current-model>" \
  --skill-name "commercetools-storefront"

The output is the GraphQL SDL for that resource. If the resource name is not recognized, the script prints the list of valid resource names — pick the correct one and re-run. Note: the SDL may contain stubbed types — referenced resources rendered as stubs, with their real type name given in a comment. Fetch any you need separately by re-running this script with that type name as --resource-name.

Fetch OpenAPI (REST) schema — Run this when you need context about a commercetools REST endpoint, request/response payload, or update action — for example, to inspect a resource's REST operations before constructing a request, or to verify a REST request/payload you have just generated against the real specification. It fetches the partial OpenAPI specification for a single commercetools resource:

node scripts/openApi-schemata.mjs \
  --resource-name "<commercetools resource, e.g. api-Cart-write, api-Customer-read, checkout-Application>" \
  --app-name "<current-app, e.g. claude, copilot, cursor, codex>" \
  --model "<current-model>" \
  --skill-name "commercetools-storefront"

The output is the OpenAPI specification (YAML) for that resource. REST resources use a read/write-split naming form (e.g. api-Cart-read, api-Cart-write). If the resource name is not recognized, the script prints the list of valid resource names — pick the correct one and re-run. Note: the spec does not include reference-expansion schemas — fetch a referenced resource's schema separately by re-running this script with that resource as --resource-name.

Key Takeaways

The BFF pattern is non-negotiable. All commercetools API calls go through a server endpoint (BFF). The browser never calls commercetools directly. Secrets are never exposed to the client bundle (no public env prefix). (This requires a server tier — see the architecture assumption above.)

Sessions are server-managed. The BFF owns session state and is the only tier that reads or writes it. How it's stored is a stack choice — a signed token in an HTTP-only cookie (stateless BFF), or a server-side session store keyed by an opaque cookie (stateful BFF). Either way the client never holds session secrets or raw commercetools credentials — only an opaque reference. Any session-signing secret must be strong and is never hardcoded or exposed to the client.

Server-rendered loads for catalog data; client state for mutable user state. Catalog/immutable data (category pages, PDPs) is loaded on the server, calling <server>/ct/* directly. Cart, account, and user-specific data are loaded into client-side state management → server endpoint → commercetools SDK.

<server>/ct/* is server-only. Never import it from a client component. Import types from the app type-mapping root (<server>/types).

Decision Steps

Build a storefront in this order — each step maps to a section of the Reference Index below:

1. Choose your stack (if exists). Pick the adapter under references/stack/<name>/ for your frontend. It owns file layout, render/routing primitives, the session mechanism, the client-state library, and deploy.
2. Implement the shared foundation. Wire the BFF boundary, sessions, commercetools client, type boundary, cart, and data-loading — references/core/.
3. Add optional core features. Layer in cross-cutting extras (e.g. recurring prices/orders) as needed — references/core/optional/.
4. Choose B2C or B2B. Load the matching surface for its domain features and rules — references/b2c/ or references/b2b/.
5. Add optional surface features. Layer in surface-specific extras .

Reference Index

Stacks

Pick the adapter for your frontend stack. Each stack folder under references/stack/<name>/ maps the framework-neutral patterns in this skill onto that stack's primitives and owns its file layout, render primitives, and deploy.

Shared Foundation (references/core/)

Core Optional Features (references/core/optional/)

B2C Storefront (references/b2c/)

B2C Optional Features (references/b2c/optional/)

B2B Storefront (references/b2b/)

B2B Optional Features (references/b2b/optional/)

Priority Tiers

CRITICAL

• BFF architecture — <server>/ct/* is server-only. Zero commercetools SDK imports in any client component. (Requires a server tier — see the architecture assumption.)
• Session & client secrets — the commercetools client secret and any session-signing secret are server-only env vars, never hardcoded and never exposed to the client bundle (no public env prefix).
• commercetools login endpoint — apiRoot.login().post(), never apiRoot.customers().login().
• B2B: as-associate chain — ALL B2B writes (cart, order, quote, approval, BU) go through apiRoot.asAssociate().*. Never use project-level apiRoot.* for user-facing B2B mutations.
• B2B: session B2B fields — businessUnitKey + storeKey + distributionChannelId + supplyChannelId + productSelectionId are always written together from getStoreChannelData(storeKey).
• B2B: three-field locale atomicity — locale, currency, country must all be updated together. Reset cartId on locale/currency change.

Framework-version gates, find overview.md of your stack.

HIGH

• Parallel fetching — Promise.all for independent fetches in server-rendered loads. No request waterfalls.
• Type safety — Frontend components import types from the app type-mapping root (<server>/types), never from <server>/ct/*.
• commercetools type boundary — Map commercetools SDK responses to app types in <server>/mappers/ before they leave <server>/ct/.
• Client state invalidation — invalidate/refresh the relevant client state after login, logout, and order placement.
• B2B: BU key in client state-manager/cache keys — all dashboard state is keyed by businessUnitKey (e.g. a [KEY, businessUnitKey] tuple) so it refreshes on BU switch.

MEDIUM

• Product Search API — Use apiRoot.products().search(), never the deprecated productProjections().search(). See the commercetools-platform skill → product-search.md.
• Server-side TTL cache — Wrap rarely-changing commercetools data in the framework's server-side cache-with-TTL. Never use it for per-user or per-session data. (Next.js: unstable_cache — see the adapter.)

Anti-Patterns Quick Reference