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

# Installation

> Install @quickbutik/kit from npm or load it from a CDN, and choose the right entry point.

## Install from npm

<CodeGroup>
  ```bash npm theme={null}
  npm install @quickbutik/kit
  ```

  ```bash pnpm theme={null}
  pnpm add @quickbutik/kit
  ```

  ```bash yarn theme={null}
  yarn add @quickbutik/kit
  ```

  ```bash bun theme={null}
  bun add @quickbutik/kit
  ```
</CodeGroup>

The package is on **public npm** under the MIT license, so you don't need any `.npmrc`, registry or token setup.

<Warning>
  If a project or home `.npmrc` maps the `@quickbutik` scope to another registry, that mapping hides the public package and the install fails with `Cannot find module '@quickbutik/kit'`. Remove the scope mapping.
</Warning>

**Requirements**

* **Node 18 or newer** on the server, because the kit needs a global `fetch`.
* **React** is an *optional* peer dependency (`^18.2 || ^19`), needed only for `@quickbutik/kit/react`. Some features (`<ProductProvider slug>`, the promise form, tag hoisting in `<SEO />`) need React 19.
* The SDK itself has **zero runtime dependencies**.

## Entry points

| Import | Contents | Server-safe |
| - | - | - |
| `@quickbutik/kit` | Everything except React and the elements: client, types, storage and cookie helpers, SEO builder, variant matrix, `ProductController`, image and money helpers, currency helpers, the consent store and the analytics hub | Yes |
| `@quickbutik/kit/sdk` | Just the client, its types, the error classes and key/scope/config helpers | Yes |
| `@quickbutik/kit/react` | Hooks and headless components. Carries a `"use client"` directive | Client only |
| `@quickbutik/kit/elements` | `configure()`, `defineElements()` and the `<qb-*>` element classes | **Browser only**. Importing it in Node throws `HTMLElement is not defined` |
| `@quickbutik/kit/global` | The script-tag bundle (`window.Quickbutik`) | Browser only |

```ts theme={null}
// Everything except React: server and browser
import { createShopkitClient, buildSeo, createRequestCookieStorage } from "@quickbutik/kit"

// Just the client and its types: a Node script, an Astro endpoint, a Worker
import { createShopkitClient } from "@quickbutik/kit/sdk"

// Hooks and headless components (client only)
import { ShopkitProvider, useCart, ProductProvider } from "@quickbutik/kit/react"

// The same composition as custom elements, for a project that is not React
import { configure, defineElements } from "@quickbutik/kit/elements"
```

<Tip>
  In a framework with server components (Next.js App Router), keep `/react` below a `"use client"` boundary and fetch catalog data on the server with the plain client from `@quickbutik/kit`.
</Tip>

## Load from a CDN (no build step)

For a page with no npm and no bundler, load the self-contained script-tag build:

```html theme={null}
<script defer
  src="https://cdn.jsdelivr.net/npm/@quickbutik/kit@1.8.0/dist/quickbutik-kit.global.js"
  data-publishable-key="qb_pk_…"
  data-currency="SEK"
  data-locale="sv-SE"></script>
```

| | |
| - | - |
| File | `dist/quickbutik-kit.global.js` (also the package's `unpkg` and `jsdelivr` entry, and `@quickbutik/kit/global`) |
| CDN | `https://cdn.jsdelivr.net/npm/@quickbutik/kit@<version>/dist/quickbutik-kit.global.js` or `https://unpkg.com/@quickbutik/kit@<version>` |
| Size (1.8.0) | About 176 KB minified, about 51 KB gzipped. One request, no dependencies |
| Global | `window.Quickbutik` |
| Target | ES2020, so it runs in every browser that supports custom elements |

<Warning>
  **Pin an exact version** in a script tag (`@1.8.0`, not `@1` or no version at all) and bump it on purpose. To self-host, copy the file out of `node_modules/@quickbutik/kit/dist/` and serve it from your own origin.
</Warning>

Use `defer` to keep the script off the critical path. The full list of `data-*` attributes is in the [script tag reference](/kit/reference/script-tag).

## Environment variables

The publishable key is public by design, so it belongs in the env var your framework exposes to the browser. Keep the `.env` file out of git anyway.

| Stack | Variable | Read as |
| - | - | - |
| Next.js | `NEXT_PUBLIC_QUICKBUTIK_PUBLISHABLE_KEY` | `process.env.NEXT_PUBLIC_QUICKBUTIK_PUBLISHABLE_KEY` |
| Vite (React, Vue, Svelte, vanilla) | `VITE_QUICKBUTIK_PUBLISHABLE_KEY` | `import.meta.env.VITE_QUICKBUTIK_PUBLISHABLE_KEY` |
| Astro | `PUBLIC_QUICKBUTIK_PUBLISHABLE_KEY` | `import.meta.env.PUBLIC_QUICKBUTIK_PUBLISHABLE_KEY` |
| Server only (Node, Workers, Hono) | `QUICKBUTIK_PUBLISHABLE_KEY` | `process.env` / the Worker's env binding |
| Script tag | none | `data-publishable-key` on the tag |

<Warning>
  Never put a `qb_pat_…` personal access token in any of these. The kit rejects one with a `ShopkitConfigError`, but a public env var would still ship it to every visitor.
</Warning>

Leave `apiUrl` and `checkoutUrl` unset in production. They default to `https://commerce.quickbutik.com` and `https://pay.quickbutik.com`.

## Versions

The current version is **1.8.0**. Install it unpinned from npm and pin it exactly in a script tag. These features need a minimum version:

| Feature | Since |
| - | - |
| Inline (embedded) checkout: `<qb-checkout>`, `checkout.mount()`, `<Checkout>` | 1.1.0. Older builds never register `<qb-checkout>`, so it renders nothing |
| `theme` (light/dark) on `checkout.start()`, `createSession()` and `mount()` | 1.2.0 |
| `theme` attribute/prop on `<qb-checkout>`, `<qb-checkout-button>` and `<Checkout>` | 1.2.1 |
| Campaign storefronts on the cart and checkout, `successMode: "inline"`, a single shared build across entry points | 1.3.0 |
| Buy now (`buyNow`, `<qb-buy-now>`), `storefrontId`, campaign-priced product reads, `cart.clear()` | 1.4.0 |
| `variant.imageId`, `product.sections`, `product.relatedProducts` in the types | 1.5.0 |
| `Category.ancestors` typed as `CategoryAncestor[]` (`{ id, name, slug }`) | 1.6.0 |
| `buildSeo({ category })` names breadcrumb parents from `Category.ancestors` | 1.7.0 |
| [Cookie consent and analytics](/kit/concepts/consent-and-analytics), **on by default**: the banner, Consent Mode, the shop's GA4 / GTM / Meta pixel, commerce events and the purchase | 1.8.0 |
| [Currencies](/kit/concepts/currencies): `currency` / `setCurrency()`, `useCurrency()`, `<qb-currency-select>`, `product.currency`, `cart.presentment` | 1.8.0 |

<Warning>
  **Upgrading to 1.8.0 changes two defaults.** Every storefront built on `<ShopkitProvider>`, `configure()`, `<qb-shop>` or the script tag now shows a cookie banner and, once the shopper agrees, loads the shop's analytics; opt out with `consent: false` in the config (`data-consent="false"`). And `configure({ currency })` / `data-currency`, which used to be formatting settings only, are now sent with every request as the currency the page browses in. For the shop's own currency the platform answers exactly as before.
</Warning>

The full history is in the package's `CHANGELOG.md` on npm.


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