Quickstart: Storefront with the SDK
You build one Next.js page that lists products from your store and a cart that shoppers can add to. It uses @ecomweb/sdk to read the catalog and @ecomweb/storefront-kit to hold the cart. Both talk to the Storefront API with your store’s publishable key.
You need Node.js 24, pnpm and the store’s publishable key. Only the store owner can see the key, in Settings › API Keys. For what the key can do, see Authentication and Create and manage API keys.
Create the project
Section titled “Create the project”You have two ways to start.
Generate a project for your store. Sign in to the CLI (see Install and sign in to the EcomWeb CLI), then run:
ecomweb storefront init ./my-shopcd my-shoppnpm devThe project already has the kit wired in and your store’s settings in .env.development.local, so you do not need to paste anything. This route also gives you a full storefront with a product list and a cart already built. Skip to Next steps, or to work on the project see Connect a self-hosted site. The sections below build the same pieces by hand in an existing app.
Add the packages to an existing Next.js 16 app. The kit needs Next.js 16 and React 19.
pnpm add @ecomweb/sdk @ecomweb/storefront-kitThen add three files. The proxy keeps the shopper’s session fresh. The two route handlers are the same-origin endpoints the kit’s sign-in and cart calls go through, so the browser never holds a token.
import { createStorefrontMiddleware } from "@ecomweb/storefront-kit/middleware";
export default createStorefrontMiddleware();
export const config = { matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],};import { createAuthRoutes } from "@ecomweb/storefront-kit/server";
export const { GET, POST } = createAuthRoutes();import { createBackendProxy } from "@ecomweb/storefront-kit/server";
export const { GET, POST, PUT, PATCH, DELETE } = createBackendProxy();Configure the publishable key
Section titled “Configure the publishable key”The kit runs in single store mode unless you change it, which is what you want. It reads three values, and Next.js only exposes NEXT_PUBLIC_ variables to browser code. Put the plain names in .env.local and copy them across in next.config.mjs.
ECOMWEB_STORE_REF=<store ref>ECOMWEB_PUBLISHABLE_KEY=<publishable key>SITE_URL=http://localhost:3000/** @type {import('next').NextConfig} */const nextConfig = { env: { NEXT_PUBLIC_ECOMWEB_STORE_REF: process.env.ECOMWEB_STORE_REF, NEXT_PUBLIC_ECOMWEB_PUBLISHABLE_KEY: process.env.ECOMWEB_PUBLISHABLE_KEY, NEXT_PUBLIC_SITE_URL: process.env.SITE_URL, },};
export default nextConfig;The API address defaults to https://apibase.ecomweb.app/api/v1. Next.js reads these values when it builds, so restart pnpm dev or build again after you change one. A missing or invalid value makes the first request fail with a message that names the variable.
Wrap your layout in the kit’s provider. It loads the store once and gives the cart and sign-in hooks to everything below it.
import type { ReactNode } from "react";import { notFound } from "next/navigation";import { getCachedStore, resolveStoreRef, StorefrontKitProvider,} from "@ecomweb/storefront-kit";
export const dynamic = "force-dynamic";
export default async function RootLayout({ children }: { children: ReactNode }) { const storeRef = await resolveStoreRef(); const store = await getCachedStore(storeRef); if (!store) notFound();
return ( <html lang="en"> <body> <StorefrontKitProvider store={store}>{children}</StorefrontKitProvider> </body> </html> );}List products
Section titled “List products”A server component can call the SDK directly. The kit exports a ready sdk that already sends your publishable key. This page asks the catalog search for the first 12 products.
import { sdk, formatPrice, resolveStoreRef } from "@ecomweb/storefront-kit";import { AddToCart } from "@/components/add-to-cart";import { CartSummary } from "@/components/cart-summary";
export const dynamic = "force-dynamic";
export default async function HomePage() { const storeRef = await resolveStoreRef(); const result = await sdk.search.searchCatalog(storeRef, { q: "*", collection: "products", page: 1, page_size: 12, }); const products = (result.data ?? []).map((hit) => hit.document);
return ( <main> <h1>Products</h1> <ul> {products.map((product) => ( <li key={product.id}> <h2>{product.name}</h2> <p>{formatPrice(product.min_price)}</p> {product.variant_mode === "simple" && ( <AddToCart productId={Number(product.id)} /> )} </li> ))} </ul> <CartSummary /> </main> );}q: "*" matches every product. Each hit’s document has the product’s id, name, slug, min_price and max_price, among other fields. A product with options has variant_mode set to "variant". The shopper must pick a variant for it, so this page only offers the button for "simple" products.
Add a cart
Section titled “Add a cart”The provider holds the cart. useCart reads it and changes it from a client component. A simple product still has one variant, so look that variant up when the shopper clicks.
"use client";
import { sdk, useCart, useStoreData } from "@ecomweb/storefront-kit";
export function AddToCart({ productId }: { productId: number }) { const { addItem } = useCart(); const store = useStoreData();
async function add() { const product = await sdk.products.getById(store.ref, productId, { include_variants: true, }); const variant = product?.variants[0]; if (!product || !variant) return;
await addItem({ id: `${product.id}-${variant.id}`, productId: product.id, variantId: variant.id, name: product.name, price: variant.price, }); }
return ( <button type="button" onClick={add}> Add to cart </button> );}"use client";
import { formatPrice, useCart, useStoreCurrency } from "@ecomweb/storefront-kit";
export function CartSummary() { const { items, itemCount, subtotal, isLoading, updateQuantity, removeItem } = useCart(); const currency = useStoreCurrency();
if (isLoading) return <p>Loading cart...</p>; if (itemCount === 0) return <p>Your cart is empty.</p>;
return ( <section> <h2>Cart ({itemCount})</h2> <ul> {items.map((item) => ( <li key={item.id}> {item.name} x {item.quantity} <button type="button" onClick={() => updateQuantity(item.id, item.quantity + 1)}> + </button> <button type="button" onClick={() => removeItem(item.id)}> Remove </button> </li> ))} </ul> <p>Subtotal: {formatPrice(subtotal, undefined, currency)}</p> </section> );}Run pnpm dev and open the page. Click Add to cart and the cart appears under the list. The cart belongs to the browser until the shopper signs in, then it moves to their account. The price on the cart comes from the API, not from the price you pass.
Next steps
Section titled “Next steps”- Place an order from the cart: Cart and checkout
- Let shoppers sign in and see their orders: Customer accounts
- Every Storefront API endpoint: Storefront API reference
- Every SDK class and function: SDK reference and storefront kit reference