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

# Installation & Quick Start

> Get started with the CommerceEngine TypeScript SDK in minutes

# TypeScript SDK

A **100% type-safe** TypeScript SDK for the CommerceEngine Storefront API — automatic token management, universal compatibility (browser, Node.js, Next.js, TanStack Start, Astro, SvelteKit), and production-ready error handling.

### Package

<Card title="@commercengine/storefront" icon="npm" href="https://www.npmjs.com/package/@commercengine/storefront">
  Universal TypeScript SDK with first-class bindings for React, Next.js, TanStack Start, Astro, SvelteKit, and Node.js.
</Card>

### Pick your integration

<CardGroup cols={2}>
  <Card title="React" icon="https://svgl.app/library/react_light.svg" href="/sdk/react-integration">
    Context providers, hooks, and component patterns for React SPAs.
  </Card>

  <Card title="Next.js" icon="https://svgl.app/library/nextjs_icon_dark.svg" href="/sdk/nextjs-integration">
    SSR, Server Actions, static rendering, and cookie-backed sessions.
  </Card>

  <Card title="TanStack Start" icon="https://svgl.app/library/tanstack.svg" href="/sdk/tanstack-start-integration">
    Server functions, route loaders, and pre-rendering.
  </Card>

  <Card title="Astro" icon="https://svgl.app/library/astro-icon-light.svg" href="/sdk/astro-integration">
    SSR pages, API routes, middleware, and static prerendering.
  </Card>

  <Card title="SvelteKit" icon="https://svgl.app/library/svelte.svg" href="/sdk/sveltekit-integration">
    Server load functions, form actions, hooks, and universal loads.
  </Card>

  <Card title="Node.js" icon="https://svgl.app/library/nodejs.svg" href="/sdk/nodejs-integration">
    Express middleware, background jobs, and server-side patterns.
  </Card>
</CardGroup>

## Installation

<Tabs>
  <Tab title="npm">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    npm install @commercengine/storefront
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    pnpm add @commercengine/storefront
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    yarn add @commercengine/storefront
    ```
  </Tab>
</Tabs>

## Quick Start

<Steps>
  <Step title="Initialize the SDK">
    ```typescript lib/storefront.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
    import { createStorefront, Environment, BrowserTokenStorage } from "@commercengine/storefront";

    const storefront = createStorefront({
      storeId: "your-store-id",
      environment: Environment.Staging, // or Environment.Production
      apiKey: "your-api-key",
      session: {
        tokenStorage: new BrowserTokenStorage("myapp_"),
      },
    });
    ```
  </Step>

  <Step title="Browse products (public — no auth needed)">
    ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const { data, error } = await storefront.public().catalog.listProducts({
      page: 1,
      limit: 20,
    });

    if (error) {
      console.error("Failed:", error.message);
    } else {
      console.log(`Found ${data?.products.length} products`);
    }
    ```
  </Step>

  <Step title="Start a session for cart, auth, and orders">
    ```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const sdk = storefront.session();
    await sdk.ensureAccessToken(); // Bootstraps anonymous session

    const { data: cart } = await sdk.cart.createCart({
      items: [{ product_id: "prod_123", variant_id: null, quantity: 1 }],
    });
    console.log("Cart created:", cart?.cart.id);
    ```
  </Step>
</Steps>

That's it — you're making API calls. The SDK handles token refresh, error typing, and session management automatically.

## Learn More

<CardGroup cols={2}>
  <Card title="Client Overview" icon="cubes" href="/sdk/client-overview">
    Public/session split, available clients, and the SDK architecture.
  </Card>

  <Card title="Configuration" icon="gear" href="/sdk/configuration">
    All config options, environments, custom base URLs, and debugging.
  </Card>

  <Card title="Token Management" icon="key" href="/sdk/token-management">
    Automatic token refresh, storage options, and auth lifecycle.
  </Card>

  <Card title="Type Safety" icon="shield" href="/sdk/type-safety">
    Auto-generated types, IntelliSense, and the `{ data, error }` pattern.
  </Card>
</CardGroup>