Production Storefront

​

Start with one install

npx skills add commercengine/skills

​

Execution contract

​

Canonical route matrix

​

Rendering and session rules

• Use public accessors for catalog and store configuration when no live user identity is needed.
• Use framework session accessors only at request- or browser-session boundaries.
• Never create anonymous sessions during build-time rendering or static generation.
• Mount the framework bootstrap once near the root for first-visit session creation.
• Returning users should hydrate from existing session cookies/storage.
• When Hosted Checkout and the Storefront SDK are both installed, the Storefront SDK is the session owner and checkout must use authMode: "provided" with token updates in both directions.

​

Production-quality catalog rules

​

PLP and search

• Use searchProducts for filtered or faceted listings; it returns flattened sellable Items/SKUs.
• Resolve category identifiers before issuing category-scoped requests. An unresolved category must not silently fall back to the full catalog.
• Escape filter values according to the search filter syntax.
• Prevent slower, older requests from replacing newer search results.
• Reset captured facets when the search query changes.

​

PDP

• Use option query parameters as canonical state for multi-option products.
• Match variants against all associated option keys.
• Disable option combinations that cannot resolve to a purchasable variant.
• Keep Add to Cart disabled until a valid variant is selected when has_variant is true.
• Allow purchase when stock_available is true or the item permits backorder.
• Use variant_id: null for products without variants.

​

SEO and structured data

• generate unique title and description metadata for category and product routes
• emit canonical URLs where appropriate
• provide Open Graph and social metadata
• emit Product and Breadcrumb structured data for PDPs
• include price, currency, availability, and aggregate rating only when valid data exists
• safely serialize JSON-LD so catalog content cannot terminate the script element
• return real 404s only for confirmed missing resources

​

Performance baseline

• prerender or cache public catalog routes where the framework supports it
• keep session work out of public root rendering
• parallelize independent reads
• preserve stable layout dimensions for images and checkout loading
• load Hosted Checkout without blocking the main render
• avoid duplicate providers, listeners, and checkout initialization
• clean up checkout listeners on unmount and guard asynchronous initialization against resurrection after teardown
• use the framework’s deployment adapter rather than assuming a Node-only runtime

​

Deployment-aware generation

• Cloudflare Workers: verify the framework adapter and workerd compatibility. Apply the documented User-Agent workaround where required by the framework/runtime combination.
• Vercel: use the framework’s supported adapter or output preset; do not carry Cloudflare-only plugins into the Vercel build.
• Netlify: use the framework’s official Netlify adapter and confirm server/edge compatibility.
• Static deployment: only prerender routes that do not require request-time session state.

​

Validation gates

​

Repository gates

[ ] dependencies install successfully
[ ] typecheck passes
[ ] lint/check passes
[ ] tests pass, when present
[ ] production build passes
[ ] deployment adapter emits the expected output

​

Commerce journey gates

[ ] public catalog renders without creating a session
[ ] first live-session action succeeds
[ ] product and variant URLs restore state after refresh
[ ] first Add to Cart creates a cart correctly
[ ] subsequent mutations preserve every requested change
[ ] Hosted Checkout initializes once and reports ready state
[ ] Storefront SDK and Hosted Checkout share one session
[ ] login/logout preserves anonymous continuity
[ ] checkout completion is handled
[ ] account and order pages reject anonymous access correctly
[ ] missing product/category behaviour is correct
[ ] transient API failure has a recoverable UI state

​

Quality gates

[ ] keyboard-accessible interactive controls
[ ] visible focus states
[ ] responsive layout on mobile and desktop
[ ] useful loading, empty, error, and unavailable states
[ ] metadata and JSON-LD validated
[ ] no secrets embedded beyond publishable storefront credentials
[ ] no raw tokens or sensitive payloads in logs

​

Copy-paste prompt

Build a production-ready Commerce Engine storefront in this repository.

First inspect the existing project, framework, routes, styles, scripts, deployment adapter, and environment conventions. Install and use the Commerce Engine skills package. Load every relevant skill rather than treating this as a single-feature task.

Use @commercengine/storefront and the framework-specific wrapper. Use public accessors for public catalog rendering and session accessors only for live cart, auth, account, and order flows. Use Commerce Engine Hosted Checkout unless the brief explicitly requires a custom checkout. When the Storefront SDK and Hosted Checkout are both present, use authMode: "provided" and synchronize tokens in both directions.

Before writing each SDK operation, retrieve its exact current contract from https://llm-docs.commercengine.io using a .md URL or Accept: text/markdown. Import Commerce Engine types directly from the SDK and do not create duplicate API interfaces.

Use https://github.com/tark-ai/ce-starter-projects as implementation evidence for the selected framework. Match its production patterns where applicable: rendering boundaries, session bootstrap, checkout lifecycle, URL state, error recovery, SEO, safe JSON-LD, performance, and deployment configuration.

Implement the complete route and customer-journey matrix appropriate to the brief. Run typecheck, lint/check, tests, and the production build. Fix failures. At the end, list what was implemented, the commands that passed, the customer journeys verified, and anything that could not be tested.