> ## Documentation Index
> Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Production Starters

> How agents and developers should use the multi-framework Commerce Engine starter repository as executable production documentation.

The Commerce Engine starter repository is executable documentation for production storefront architecture. It contains two independent storefront brands implemented across multiple frameworks, allowing developers and agents to compare equivalent commerce features without confusing framework differences with platform behaviour.

<Card title="Commerce Engine starter projects" icon="github" href="https://github.com/tark-ai/ce-starter-projects">
  Browse the production storefront monorepo.
</Card>

## Repository model

The repository contains two complete visual brands:

* **Linea** — a jewellery storefront
* **Little Things** — a gadgets storefront

Each brand is implemented across:

| Framework          | Rendering model               | Commerce Engine integration                                                         |
| ------------------ | ----------------------------- | ----------------------------------------------------------------------------------- |
| Vite + React       | Client-rendered SPA           | Core `createStorefront()` public/session accessors                                  |
| TanStack Start     | SSR + prerendered React       | First-party TanStack Start wrapper, route loaders, client session, server functions |
| Next.js App Router | RSC, SSG/ISR, client islands  | First-party Next.js wrapper and request-aware accessors                             |
| Astro              | Static/SSR pages with islands | First-party Astro wrapper plus root Hosted Checkout helpers                         |
| SvelteKit          | Universal and server loads    | First-party SvelteKit wrapper with cookie-bound server access                       |

The shared packages are organized by brand so feature logic and design systems can be reused without forcing one framework's rendering model onto another.

## What the starters demonstrate

The repository is not only a visual theme collection. It demonstrates production decisions that are difficult to communicate through isolated snippets:

<CardGroup cols={2}>
  <Card title="Rendering boundaries" icon="arrows-split-up-and-left">
    Public catalog reads are separated from request- or browser-session work, allowing fast prerendering without creating anonymous sessions at build time.
  </Card>

  <Card title="Session ownership" icon="key">
    Storefront SDK bootstrap and Hosted Checkout use one shared session with bidirectional token synchronization.
  </Card>

  <Card title="Catalog UX" icon="store">
    Category resolution, faceted search, pagination, variant option state, recommendations, and resilient loading behaviour.
  </Card>

  <Card title="SEO" icon="magnifying-glass-chart">
    Route metadata, canonical URLs, Product and Breadcrumb JSON-LD, real not-found responses, and safe serialization of catalog content.
  </Card>

  <Card title="Performance" icon="gauge-high">
    Prerendering, ISR where applicable, parallel data fetching, stable layouts, image optimization, and framework-appropriate hydration.
  </Card>

  <Card title="Deployment" icon="cloud-arrow-up">
    Framework-specific output and adapters for modern serverless and edge platforms rather than a Node-only architecture.
  </Card>
</CardGroup>

## How agents should use the repository

An agent should not copy an entire starter blindly. It should use the closest implementation as evidence for framework-specific concerns while preserving the target project's design and conventions.

<Steps>
  <Step title="Choose the closest framework implementation">
    Match the target application's framework and rendering mode. Use the second brand as a cross-check when a pattern appears brand-specific.
  </Step>

  <Step title="Trace the feature end to end">
    For a feature such as product detail, inspect the route loader/server component, shared feature component, query hooks, URL state, metadata, structured data, and Add to Cart integration together.
  </Step>

  <Step title="Separate invariants from implementation choices">
    Commerce Engine invariants—such as public/session boundaries, variant IDs, or Hosted Checkout token sync—must be preserved. Styling libraries, component composition, and route names can follow the target project.
  </Step>

  <Step title="Check recent hardening patterns">
    Prefer the current implementation over older copied snippets. The starters include practical fixes for stale search responses, category scope, safe JSON-LD, asynchronous bootstrap cleanup, transient API failures, and build resilience.
  </Step>

  <Step title="Run the target project's own checks">
    A pattern working in a starter does not prove it works after transplantation. Typecheck, lint, test, build, and exercise the target application.
  </Step>
</Steps>

## Framework evidence checklist

When generating a storefront, inspect these areas in the chosen starter:

### Foundation

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
[ ] environment variable names
[ ] SDK factory and environment selection
[ ] public/client/server accessor boundaries
[ ] root session bootstrap
[ ] Hosted Checkout initialization and cleanup
[ ] provider/query-client composition
```

### Catalog

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
[ ] category resolution before scoped queries
[ ] listProducts vs listSkus vs searchProducts choice
[ ] filter escaping and URL state
[ ] stale request protection
[ ] variant option resolution
[ ] stock/backorder gating
[ ] recommendation queries
```

### Rendering and quality

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
[ ] public route prerendering or caching
[ ] loading and fallback states
[ ] confirmed 404 vs transient API failure
[ ] metadata and social previews
[ ] safe JSON-LD serialization
[ ] responsive and keyboard-accessible UI
[ ] image dimensions and optimization
```

### Deployment

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
[ ] correct framework adapter/preset
[ ] runtime-specific fetch requirements
[ ] static-route exclusions
[ ] environment variables documented in .env.example
[ ] build output tested on the target platform
```

## Important patterns reflected in the starters

### Do not silently broaden a category query

A category page should resolve the category first. If the slug does not resolve yet, do not omit `category_id` and accidentally return the whole catalog. Render a loading/not-found state or retry resolution.

### Distinguish missing data from a failed request

A successful product request with no product can produce a real 404. A timeout or server failure should normally produce a recoverable fallback rather than permanently serving a not-found page.

### Safely serialize JSON-LD

Product names and descriptions are catalog data. Escape characters that could terminate an inline `<script>` before injecting JSON-LD into the page.

### Guard asynchronous bootstrap cleanup

If a root component unmounts while session and checkout initialization are still awaiting network work, do not recreate the checkout instance after cleanup has already run.

### Protect search and wishlist state from races

A slower request must not overwrite a newer query. Likewise, concurrent wishlist mutations should commit responses in a defined order rather than whichever response arrives last.

## Running a starter

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Clone and install
git clone https://github.com/tark-ai/ce-starter-projects.git
cd ce-starter-projects
bun install

# Configure credentials
cp .env.example .env

# Run one app
bun run dev:linea-next
```

See the repository README and each application's `.env.example` and scripts for the exact commands and deployment configuration.

<Info>
  The starters are reference implementations, not a substitute for the skills package or LLM-first contract lookup. Use skills for decisions, LLM docs for exact current operations and types, and starters for integrated production patterns.
</Info>