Skip to content

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.

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:

Terminal window
ecomweb storefront init ./my-shop
cd my-shop
pnpm dev

The 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.

Terminal window
pnpm add @ecomweb/sdk @ecomweb/storefront-kit

Then 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.

proxy.ts
import { createStorefrontMiddleware } from "@ecomweb/storefront-kit/middleware";
export default createStorefrontMiddleware();
export const config = {
matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
};
app/api/auth/[...route]/route.ts
import { createAuthRoutes } from "@ecomweb/storefront-kit/server";
export const { GET, POST } = createAuthRoutes();
app/api/backend/[...path]/route.ts
import { createBackendProxy } from "@ecomweb/storefront-kit/server";
export const { GET, POST, PUT, PATCH, DELETE } = createBackendProxy();

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.

.env.local
ECOMWEB_STORE_REF=<store ref>
ECOMWEB_PUBLISHABLE_KEY=<publishable key>
SITE_URL=http://localhost:3000
next.config.mjs
/** @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.

app/layout.tsx
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>
);
}

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.

app/page.tsx
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.

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.

components/add-to-cart.tsx
"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>
);
}
components/cart-summary.tsx
"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.