Next.js adapter

initStorekit() — server resources, cookie-backed cart and auth, and the proxy handler.

@usestorekit/sdk/next is server-only (it imports next/headers). Use it in React Server Components, generateMetadata, Server Actions, and route handlers.

initStorekit()

lib/storekit.ts

import { initStorekit } from "@usestorekit/sdk/next";

export const storekit = initStorekit();

It reads configuration from the environment, or from the options you pass:

Prop

Type

initStorekit() throws synchronously if apiURL or storeKey is missing, and warns if baseURL is unset (payment returns may break).

A module-scoped instance is safe — cookies are read lazily per request.

What you get

const storekit = initStorekit();

storekit.products;   // catalog resources — see the reference
storekit.categories;
storekit.store;
storekit.search;
storekit.coupons;
storekit.checkout;
storekit.customer;

storekit.cart;       // cookie-backed cart (no cart id needed)
storekit.auth;       // cookie-backed auth (httpOnly session)

storekit.handler();  // the catch-all proxy for the browser
storekit.$client;    // escape hatch: the underlying core client

Direct resources (products, customer, …) work exactly like the core client — full method reference under Reference. Public catalog reads are auto-cached with the revalidate you configured.

The cart id lives in an httpOnly cookie, so you never pass it around:

await storekit.cart.current();              // Cart | null
await storekit.cart.count();                // number (total quantity)
await storekit.cart.add({ variantId, quantity: 1 });
await storekit.cart.setQuantity(lineId, 3);
await storekit.cart.remove(lineId);
await storekit.cart.clear();

add, setQuantity, remove, and clear write cookies, so they only work in a Server Action or Route Handler — Next.js can't set cookies during render. Reads (current, count) work anywhere on the server.

await storekit.auth.requestOtp(phone);
await storekit.auth.verifyOtp(phone, otp); // sets httpOnly session cookie, claims guest cart
await storekit.auth.session();             // Result<Customer> (401 error if logged out)
await storekit.auth.logout();              // clears the session cookie

The proxy handler

storekit.handler() returns Next route handlers. Mount it once:

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

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

export const { GET, POST, PUT, PATCH, DELETE } = storekit.handler();

It serves the browser client and:

Injects the store key and session token on the server.
Caches public catalog reads.
Manages the cart and session cookies.
Forwards /api/storefront/v1/* to the API, rejecting path traversal.
Overrides storefrontUrl on checkout with your configured baseURL.

It never echoes the session token to the browser — only the customer object.

Caching & revalidation

Public reads are tagged storekit:<resource> (e.g. storekit:products). Revalidate after a content change:

import { revalidateTag } from "next/cache";
revalidateTag("storekit:products");

Override per call with revalidate, tags, or cache in the options argument.

initStorekit()

What you get

Cookie-backed cart

Cookie-backed auth

The proxy handler

Caching & revalidation

On this page