Installation

Install from npm

npm install @quickbutik/kit

pnpm add @quickbutik/kit

yarn add @quickbutik/kit

bun add @quickbutik/kit

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

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.

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

// 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"

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.

Load from a CDN (no build step)

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

<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

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.

Use defer to keep the script off the critical path. The full list of data-* attributes is in the script tag reference.

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

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.

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, on by default: the banner, Consent Mode, the shop’s GA4 / GTM / Meta pixel, commerce events and the purchase	1.8.0
Currencies: `currency` / `setCurrency()`, `useCurrency()`, `<qb-currency-select>`, `product.currency`, `cart.presentment`	1.8.0

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.

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

Getting Started

Vanilla JavaScript

React

Web Components

Concepts

API Reference

Install from npm

Entry points

Load from a CDN (no build step)

Environment variables

Versions

​Install from npm

​Entry points

​Load from a CDN (no build step)

​Environment variables

​Versions

Install from npm

Entry points

Load from a CDN (no build step)

Environment variables

Versions