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

# One-prompt custom storefront (Lovable, v0, Cursor)

> Build a custom Quickshops storefront with Lovable, v0.dev, or Cursor. Use useStore() from @quickshops/sdk — one import for buy-now, catalog, cookies, and checkout.

<Note>
  Headless API access requires a **Pro** plan and an API key from **Settings → API keys**. Keep the key on your server — never in the browser.
</Note>

Ship a custom-looking shop without rebuilding payments. Quickshops stays the commerce brain. Your Lovable / v0 / Cursor app is the UI.

Use **`@quickshops/sdk@1.1.0+`** (`useStore()` + `@quickshops/sdk/react`).

```ts theme={null}
import { useStore } from "@quickshops/sdk";
import { Storefront, toStoreProducts } from "@quickshops/sdk/react";

const { buyNow, loadCatalog, getCheckoutSession } = useStore();
```

Server: `useStore()`. Client UI: `@quickshops/sdk/react` composition primitives (never the API key).

**v1 scope:** SSR App Router for SEO. Secret `qk_` only. No publishable browser keys. Catalog loads on the server; buttons call Server Actions.

## One prompt

1. Upgrade to **Pro**, connect Stripe under **Payments**, issue a key under **Settings → API keys**.
2. Open Lovable, [v0.dev](https://v0.dev), Cursor, or Bolt with a Next.js App Router project.
3. Paste:

```text theme={null}
Build a Next.js App Router TypeScript storefront that sells via Quickshops.

SSR-first for SEO (Server Components for catalog/PDP). No publishable API keys.
Install: npm add @quickshops/sdk server-only react

Server: use ONLY useStore from @quickshops/sdk (import "server-only").
Client UI: use @quickshops/sdk/react composition primitives (Storefront.Provider, Storefront.Product slots, BuyButton, CheckoutSuccess).
Use shadcn-style theme tokens already in the project (bg-primary, text-card-foreground, etc.) — do not invent a parallel design system.
Do NOT raw-fetch api.quickshops.app from the browser. Do NOT invent pk_ / publishable keys.
Do NOT hand-roll successUrl/cancelUrl or cart cookies.
Do NOT put HEADLESS_API_KEY in client components or NEXT_PUBLIC_*.
useStore is a server factory, not a React hook — never import it in "use client" files.

Env (server only):
- HEADLESS_API_KEY=qk_...
- HEADLESS_API_URL=https://api.quickshops.app (optional)
- SITE_URL=https://this-site-absolute-https-origin

lib/quickshops.ts:
import "server-only";
import { useStore } from "@quickshops/sdk";
export const store = useStore();

Default flow = buy-now (no cart cookie):
1. Home: store.loadCatalog() → Storefront.Provider with toStoreProducts(products) and actions={{ buy: buyProduct }} → Storefront.Grid
2. Buy action: store.buyNow({ productId }) → redirect(url)
3. Success: CheckoutSuccess with store.getCheckoutSession(session_id); store.clearCartId(await cookies())

Optional cart only if needed: store.addToCart(await cookies(), { productId }), store.checkoutCart({ cartId }).

Handle error codes: CART_EMPTY, CART_MIXED_TYPES, PAYMENTS_NOT_CONFIGURED, STORE_UNPUBLISHED, RATE_LIMITED.

Ship a working SSR storefront I can set env vars on and complete a test purchase with.
```

4. Set env vars on the host:

```bash theme={null}
HEADLESS_API_KEY=qk_...
HEADLESS_API_URL=https://api.quickshops.app
SITE_URL=https://your-custom-site.example
```

## Ideal hello-world

| Step    | Call                                            |
| ------- | ----------------------------------------------- |
| Home    | `store.loadCatalog()`                           |
| Buy     | `store.buyNow({ productId })` → `redirect(url)` |
| Success | `store.getCheckoutSession(sessionId)`           |

## Why a server boundary

`qk_` keys are secrets. The buyer’s browser talks to **your** Server Actions; your server uses `useStore()`.

```
Browser → your Next.js server → useStore() → Stripe Checkout URL
```

## Agent skill

```bash theme={null}
npx skills add valtterisa/quickshops --skill quickshops-headless-storefront
```

## Next steps

<CardGroup cols={2}>
  <Card title="SDK install" icon="terminal" href="/sdk/installation">
    Package install and method reference.
  </Card>

  <Card title="React components" icon="component" href="/sdk/react">
    Storefront.\* composition primitives and CheckoutSuccess.
  </Card>

  <Card title="Framework guides" icon="code" href="/sdk/framework-guides">
    Next.js and other SSR frameworks.
  </Card>

  <Card title="API overview" icon="book-open" href="/api/overview">
    REST reference (prefer useStore in apps).
  </Card>
</CardGroup>