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

# Quickstart

> Let's get you up and running with the Commerce Engine Storefront API. This guide covers the basics: obtaining credentials, understanding environments, and making your first API call.

The fastest production path is the unified TypeScript SDK. Public catalog reads do not require a user session; cart, authentication, account, and order flows use an anonymous or logged-in session.

<Info>
  You need a Commerce Engine Store ID and publishable Storefront API key. [Get them from the Admin Portal](/docs/storefront/credentials) — that page also explains the channel model, which decides which products your key can see.
</Info>

## Scaffold it in one command

If you are starting a new storefront, skip the manual setup entirely:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm create commercengine@latest
```

It asks what you are building, then downloads a full storefront — catalog, cart,
Hosted Checkout, SEO and agent tools already wired — and writes your credentials
into `.env` with the right variable prefix for your framework. `pnpm`, `yarn` and
`bun` work the same way.

Every prompt has a flag, so agents and CI never hit an interactive question:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm create commercengine@latest my-store -- \
  --template soja --framework next --yes
```

The same command adds Commerce Engine to a project you already have — it writes
only the integration layer and leaves your framework, router and build setup
alone:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm create commercengine@latest . -- --mode existing --framework next
```

<Card title="Browse the starters" icon="rocket" href="/docs/starters/overview">
  Three storefront designs, each built on five frameworks.
</Card>

The rest of this page is the manual path — what the CLI does for you, and what
to do when you are wiring an existing app by hand.

## 1. Install the SDK

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install @commercengine/storefront
```

For AI-assisted implementation, also install the Commerce Engine skills package:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx skills add commercengine/skills
```

## 2. Set environment variables

Use the public environment-variable prefix required by your framework:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Vite / TanStack Start
VITE_STORE_ID=your-store-id
VITE_API_KEY=your-api-key
VITE_CE_ENV=staging

# Next.js
NEXT_PUBLIC_STORE_ID=your-store-id
NEXT_PUBLIC_API_KEY=your-api-key
NEXT_PUBLIC_CE_ENV=staging

# Astro / SvelteKit
PUBLIC_STORE_ID=your-store-id
PUBLIC_API_KEY=your-api-key
PUBLIC_CE_ENV=staging
```

Keep an `.env.example` in the repository and exclude real `.env` files from version control.

## 3. Initialize the SDK

For a browser SPA:

```typescript lib/storefront.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import {
  BrowserTokenStorage,
  Environment,
  createStorefront,
} from "@commercengine/storefront";

export const storefront = createStorefront({
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  environment:
    import.meta.env.VITE_CE_ENV === "production"
      ? Environment.Production
      : Environment.Staging,
  session: {
    tokenStorage: new BrowserTokenStorage("myapp_"),
  },
});

export const publicSdk = storefront.public();
export const sdk = storefront.session();
```

For Next.js, TanStack Start, Astro, or SvelteKit, use the first-party framework wrapper instead of the SPA factory:

<CardGroup cols={2}>
  <Card title="Next.js" icon="https://svgl.app/library/nextjs_icon_dark.svg" href="/docs/sdk/nextjs-integration">
    App Router, Server Components, Server Actions, SSG/ISR, and cookie-backed sessions.
  </Card>

  <Card title="TanStack Start" icon="https://svgl.app/library/tanstack.svg" href="/docs/sdk/tanstack-start-integration">
    Route loaders, prerendering, server functions, and client sessions.
  </Card>

  <Card title="Astro" icon="https://svgl.app/library/astro-icon-light.svg" href="/docs/sdk/astro-integration">
    Static/SSR pages, islands, middleware, and request cookies.
  </Card>

  <Card title="SvelteKit" icon="https://svgl.app/library/svelte.svg" href="/docs/sdk/sveltekit-integration">
    Universal loads, server loads, actions, hooks, and cookie-backed sessions.
  </Card>
</CardGroup>

## 4. Make a public catalog request

Public reads are publishable-key-backed and do not create anonymous users or write session storage.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const { data, error } = await publicSdk.catalog.listProducts({
  page: 1,
  limit: 20,
});

if (error) {
  console.error(error.message);
} else {
  console.log(data?.products ?? []);
}
```

Use public accessors for products, categories, search, recommendations, and store configuration when the response does not depend on a live user session.

## 5. Start a live session

Cart, wishlist, authentication, customer, order, and payment operations use the session accessor. You may establish the anonymous session eagerly at application startup:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
await sdk.ensureAccessToken();
```

Most session methods can also ensure the session internally. Centralize eager bootstrap once rather than calling `ensureAccessToken()` before every feature request.

Create the cart with the first item—Commerce Engine does not create empty carts:

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const { data, error } = await sdk.cart.createCart({
  items: [
    {
      product_id: "product-id",
      variant_id: null,
      quantity: 1,
    },
  ],
});

if (error) {
  console.error(error.message);
} else {
  console.log(data?.cart);
}
```

For products with variants, pass the resolved `variant_id`; for products without variants, pass `null`.

## 6. Add Hosted Checkout

Hosted Checkout is the recommended checkout implementation for most storefronts. It supplies the cart drawer, authentication, addresses, fulfilment, coupons, loyalty, payments, and confirmation UI.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install @commercengine/checkout
```

When the Storefront SDK is present, it must own the session. Initialize checkout with `authMode: "provided"` and synchronize token changes in both directions. Follow the framework-specific pattern:

<CardGroup cols={2}>
  <Card title="Hosted Checkout overview" icon="bag-shopping" href="/docs/hosted-checkout/overview">
    Architecture, package selection, and integration choices.
  </Card>

  <Card title="Configuration" icon="code" href="/docs/hosted-checkout/configuration">
    Authentication modes, callbacks, methods, events, and Quick Buy.
  </Card>
</CardGroup>

## 7. Retrieve exact SDK contracts

Before implementing a feature, retrieve the current operation and schema definitions from the LLM-first reference:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -H "Accept: text/markdown" \
  https://llm-docs.commercengine.io/storefront/operations/create-cart
```

Agents without custom-header support can append `.md`:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://llm-docs.commercengine.io/storefront/operations/create-cart.md
```

## Direct REST integration

Use direct REST calls when you are building a non-TypeScript client, an integration that cannot use the SDK, or a custom backend façade. In that mode you are responsible for token storage, refresh, retry, and response-envelope handling.

* Staging base URL: `https://staging.api.commercengine.io/api/v1/{store_id}/storefront`
* Production base URL: `https://prod.api.commercengine.io/api/v1/{store_id}/storefront`

Public operations can use the publishable API key where declared by the operation contract. Live session operations use Bearer tokens obtained through `/auth/anonymous`, login, or refresh flows. Use the generated API reference for exact per-operation security requirements.

## Next steps

<CardGroup cols={2}>
  <Card title="Production storefront" icon="store" href="/docs/ai/production-storefront">
    Full agent execution contract and production validation gates.
  </Card>

  <Card title="Catalog" icon="boxes-stacked" href="/docs/storefront/catalog">
    Product, Item/SKU, variant, search, and PDP decisions.
  </Card>

  <Card title="Authentication" icon="lock" href="/docs/storefront/authentication">
    Anonymous, OTP, password, login, logout, and session continuity.
  </Card>

  <Card title="Cart" icon="cart-shopping" href="/docs/storefront/cart">
    First-add behaviour, cart mutation, recovery, discounts, and totals.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.