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

# Quickbutik Kit

> Build your own storefront on any stack with @quickbutik/kit, using your Quickbutik catalog, cart and hosted checkout.

`@quickbutik/kit` is Quickbutik's **bring-your-own-frontend** SDK. With it you can build the storefront in whatever you like: Next.js, Astro, Vue, Svelte, a plain HTML page, or a page in a site builder. Quickbutik is the commerce engine behind it: products, stock, the cart, the hosted checkout, orders, receipts, VAT and bookkeeping.

Everything runs on a single **publishable key** (`qb_pk_…`) that is safe to ship to a browser. The package is MIT-licensed and on public npm, has no runtime dependencies, and runs the same way on a server and in a browser.

```ts theme={null}
import { createShopkitClient } from "@quickbutik/kit"

const shopkit = createShopkitClient({
  publishableKey: process.env.NEXT_PUBLIC_QUICKBUTIK_PUBLISHABLE_KEY!,
})

const { data: products } = await shopkit.products.list({ limit: 12 })
await shopkit.cart.add({ productId: products[0].id })
const { url } = await shopkit.checkout.start({
  successUrl: "https://myshop.com/success",
  backUrl: "https://myshop.com/",
})
location.assign(url) // the shopper pays in the hosted checkout, then comes back to /success/<orderNumber>
```

## How a sale works

```text theme={null}
your storefront (publishable key)                hosted Quickbutik checkout              your storefront
catalog → cart → checkout.start()  ──────────►   address · shipping · payment   ──────►  /success/<orderNumber>
                                                 Swish · Klarna · Vipps MobilePay        poll the confirmation
                                                 iDEAL · Apple Pay · Google Pay · cards
```

Your storefront owns everything **before and after** the payment: the catalog, product pages, the cart, the checkout button and the thank-you page. The hosted checkout owns payment, shipping choice, discount codes and receipts. You never render a payment form and never handle card data.

The same hosted checkout can also run **inline on your own page**, in a frame the kit creates and drives. See [Embedded checkout](/kit/concepts/embedded-checkout). The full-page redirect stays the default and the fallback.

## What the kit is, and what it is not

<CardGroup cols={2}>
  <Card title="It is" icon="check">
    The catalog (products, search, variants, categories, shop branding), a server-owned cart, the checkout handoff and order confirmation for the thank-you page. It also remembers the small bits of state every storefront needs (the cart id, the checkout session and the shopper's currency), handles [cookie consent and the shop's analytics](/kit/concepts/consent-and-analytics), and prices everything in the shopper's [currency](/kit/concepts/currencies) when the shop offers more than one.
  </Card>

  <Card title="It is not" icon="xmark">
    A payment integration (the hosted checkout owns the payment providers, PCI scope, 3-D Secure and wallets), a data-fetching library, or a UI kit. The React and web components render **no markup of their own**, so you own all of the DOM and all of the styling.
  </Card>
</CardGroup>

The few deliberate markup exceptions are `<ProductImage />` / `<qb-product-image>` (one `<img>`), the embedded checkout's `<iframe>`, `<qb-currency-select>`'s `<select>` when you give it no markup, and the default cookie consent banner, which renders only when you don't provide your own.

## Two keys, two channels

Keeping these two apart is the most important rule when building on Quickbutik.

| Channel | Key | Host | Where it may live |
| - | - | - | - |
| **Sell**: the storefront your visitors use | Publishable key `qb_pk_…` | `https://commerce.quickbutik.com/v2` | Client code, public env vars. Safe to expose |
| **Manage**: products, orders, customers | Personal access token `qb_pat_…` | `https://api.quickbutik.com/v2` | Server code and a gitignored `.env` only. Never in a browser |

The publishable key reads the visible catalog, runs carts and opens the hosted checkout. It can't read orders, change products or take payment. The kit **refuses** a `qb_pat_` key outright, so it can't end up in a browser bundle by accident. Read more in [Publishable keys](/kit/publishable-keys).

## Entry points

The kit has four entry points over one framework-free core, plus a script-tag build:

| Import | Contains | Runs on |
| - | - | - |
| `@quickbutik/kit` | Client, types, storage helpers, SEO builder, variant matrix, image and money helpers. Everything except React and the elements | Server and browser |
| `@quickbutik/kit/sdk` | Just the client and its types | Server and browser |
| `@quickbutik/kit/react` | Hooks and headless components (`"use client"`) | Browser, below a client boundary |
| `@quickbutik/kit/elements` | Headless custom elements (`<qb-product>`, `<qb-cart>`, …) | Browser only |
| `quickbutik-kit.global.js` | All of the above as `window.Quickbutik`, with the elements pre-registered | Browser only, no build step |

## Pick your flavour

Pick one flavour for each page, based on your stack. Don't mix the React layer and the elements on the same page, because you'd end up with two cart stores.

<CardGroup cols={2}>
  <Card title="Script tag" icon="code" href="/kit/web-components/setup">
    Plain HTML, Webflow, WordPress or a CMS theme. You add one `<script>` tag plus markup, and write no JavaScript of your own.
  </Card>

  <Card title="Web components" icon="puzzle-piece" href="/kit/web-components/setup">
    Vue, Svelte, Astro, Nuxt or a Vite project without React. `@quickbutik/kit/elements`.
  </Card>

  <Card title="React" icon="react" href="/kit/react/setup">
    React, Next.js, Remix, TanStack Start. Provider, hooks and headless components from `@quickbutik/kit/react`.
  </Card>

  <Card title="Vanilla JS" icon="js" href="/kit/vanilla/setup">
    Your own rendering, or a server (Node, Hono, Workers, Astro endpoints). The client from `@quickbutik/kit`.
  </Card>
</CardGroup>

## Building with an AI agent

If you build with an AI coding agent (Claude Code, Cursor, Lovable, v0, Replit and others), point it at **[quickbutik.com/agents.md](https://quickbutik.com/agents.md)**. It is the agent-facing source of truth for building on Quickbutik. It covers creating a shop, the storefront kit, the Storefront and Merchant APIs, and going live. Add two lines like these to the project's `AGENTS.md` or `CLAUDE.md`:

```text theme={null}
Before any work on the shop, products, cart or checkout: fetch https://quickbutik.com/agents.md
and follow it. Do not rely on memory.
```

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/kit/quickstart">
    A catalog, a cart and a checkout in five minutes.
  </Card>

  <Card title="Checkout flow" icon="credit-card" href="/kit/concepts/checkout">
    The handoff, the `successUrl` rules and the thank-you page.
  </Card>
</CardGroup>


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