Installation & setup

Install the SDK, configure environment variables, and understand the project pieces.

Install

npm install @usestorekit/sdk zod

Node 18 or newer.
zod ^3.25 is a peer dependency.
next >=14 and react >=18 are optional peers — only needed for the framework adapters.

Environment variables

The Next.js adapter reads these automatically. Set them in .env.local (and your hosting provider for production):

Prop

Type

You can also pass any of these explicitly to initStorekit({ apiURL, storeKey, baseURL, outletId }) instead of using env vars.

The pieces of a Next.js integration

A complete setup has four small files. The quickstart walks through them; here's the map:

lib/storekit.ts

The server instance from initStorekit(). Used in Server Components, Server Actions, and route handlers.

app/api/storefront/[...path]/route.ts

The catch-all proxy from storekit.handler(). The browser talks to this, not the API directly.

lib/storekit-client.ts

The browser client from createStorekitClient(), exposing hooks like useCart().

app/payment/callback/page.tsx

The return page after payment, using usePaymentConfirmation().

Why a server proxy?

Your store key is a secret. If the browser called the API directly, the key would be exposed. Instead:

The browser calls your same-origin route handler (/api/storefront/...).
The handler injects the store key and the customer's session token on the server.
It forwards the request to the Storefront API and streams the response back.

The customer's session lives in an httpOnly cookie — it's never readable by JavaScript. See Authentication for details.

Verifying it works

Drop this into a Server Component and load the page:

import { storekit } from "@/lib/storekit";

export default async function Health() {
  const { data, error } = await storekit.store.get();
  return <pre>{error ? error.code : data.name}</pre>;
}

If you see your store's name, you're connected. If you see an error code like UNAUTHORIZED, double-check STOREFRONT_STORE_KEY.