Next.js

The @commercengine/storefront/nextjs package provides a Next.js-specific wrapper around the core Storefront SDK. It gives you three accessors — publicStorefront(), serverStorefront(), and clientStorefront() — so the right token strategy is used automatically in every rendering context.

NPM Package

@commercengine/storefront

Next.js integration for Commerce Engine Storefront SDK. Import from @commercengine/storefront/nextjs.

@commercengine/storefront-sdk-nextjs is deprecated. See the migration table below if you are upgrading.

Installation

npm install @commercengine/storefront

pnpm add @commercengine/storefront

yarn add @commercengine/storefront

Quick Start

Set Environment Variables

Add your store credentials to .env.local:

.env.local

NEXT_PUBLIC_STORE_ID=your-store-id
NEXT_PUBLIC_API_KEY=your-api-key

NEXT_PUBLIC_API_KEY is safe for client-side use — it is scoped to public storefront operations.

Create the Storefront Config

lib/storefront.ts

import { Environment } from "@commercengine/storefront";
import { createNextjsStorefront } from "@commercengine/storefront/nextjs";

export const storefront = createNextjsStorefront({
  storeId: process.env.NEXT_PUBLIC_STORE_ID!,
  apiKey: process.env.NEXT_PUBLIC_API_KEY!,
  environment: Environment.Staging, // or Environment.Production
  tokenStorageOptions: { prefix: "myapp_" },
});

createNextjsStorefront() does not infer credentials from environment variables — you must pass storeId and apiKey explicitly.

Create the StorefrontBootstrap Component

A Client Component that establishes the anonymous session on first visit. It renders nothing visible.

components/storefront-bootstrap.tsx

"use client";

import { useEffect } from "react";
import { storefront } from "@/lib/storefront";

export function StorefrontBootstrap() {
  useEffect(() => {
    storefront.bootstrap().catch(console.error);
  }, []);
  return null;
}

bootstrap() is deduped and idempotent. If session cookies already exist (returning user), it is a no-op.

Mount in Root Layout

The root layout stays a Server Component — StorefrontBootstrap is a Client Component child rendered inside it.

app/layout.tsx

import { storefront } from "@/lib/storefront";
import { StorefrontBootstrap } from "@/components/storefront-bootstrap";

const { data: storeConfig } = await storefront
  .publicStorefront()
  .store.getStoreConfig();

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <StorefrontBootstrap />
        <header>{storeConfig?.store_config?.brand.name}</header>
        {children}
      </body>
    </html>
  );
}

Always use publicStorefront() in the root layout. Do not call serverStorefront() or clientStorefront() here — the root layout should not participate in the user session.

Accessor Rules

Use the right accessor for each rendering context:

Context	Accessor	Why
Root Layout	`storefront.publicStorefront()`	Root layouts should stay public — no live user session
Build time / SSG / `generateMetadata`	`storefront.publicStorefront()`	No request context at build time
Public Server Component	`storefront.publicStorefront()`	Public reads that don’t need a session
Session-aware Server Component	`await storefront.serverStorefront()`	Auto-reads cookies via `next/headers`
Server Action / Route Handler	`await storefront.serverStorefront()`	Can read and write cookies
Client Component	`storefront.clientStorefront()`	Uses the browser-side session client

serverStorefront() is async — it dynamically imports next/headers and uses React cache() to dedupe within a single request. clientStorefront() throws if called on the server. serverStorefront() throws if called in the browser.

Key Patterns

Public Server Component

Fetch catalog data without touching the user session.

app/products/page.tsx

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

export default async function ProductsPage() {
  const sdk = storefront.publicStorefront();
  const { data, error } = await sdk.catalog.listProducts({ page: 1, limit: 20 });

  if (error) return <p>Error: {error.message}</p>;

  return (
    <div>
      {data?.products.map((product) => (
        <div key={product.id}>{product.name}</div>
      ))}
    </div>
  );
}

Session-Aware Server Component

Read session-scoped data such as account details or wish lists.

app/account/page.tsx

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

export default async function AccountPage() {
  const sdk = await storefront.serverStorefront();
  const { data, error } = await sdk.customer.getCustomer();

  if (error) return <p>Error: {error.message}</p>;
  return <div>Welcome, {data?.customer?.first_name}</div>;
}

Server Actions (Mutations)

Server Actions can read and write cookies, making them ideal for auth and cart mutations.

app/actions.ts

"use server";

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

export async function loginWithEmail(email: string) {
  const sdk = await storefront.serverStorefront();

  const { data, error } = await sdk.auth.loginWithEmail({
    email,
    register_if_not_exists: true,
  });

  if (error) return { error: error.message };
  return { otp_token: data?.otp_token, otp_action: data?.otp_action };
}

export async function addToCartAction(
  cartId: string,
  productId: string,
  variantId: string | null,
) {
  const sdk = await storefront.serverStorefront();
  const { data, error } = await sdk.cart.addDeleteCartItem(
    { id: cartId },
    { product_id: productId, variant_id: variantId, quantity: 1 }
  );
  return { data: data?.cart, error: error?.message };
}

Static Site Generation (SSG)

Use publicStorefront() for generateStaticParams and any build-time rendering — no session is available at build time.

app/products/[slug]/page.tsx

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

export async function generateStaticParams() {
  const sdk = storefront.publicStorefront();
  const { data } = await sdk.catalog.listProducts({ limit: 100 });

  return (data?.products ?? []).map((product) => ({
    slug: product.slug || product.id,
  }));
}

export default async function ProductPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const sdk = storefront.publicStorefront();
  const { data, error } = await sdk.catalog.getProductDetail({
    product_id_or_slug: slug,
  });

  if (error || !data) return <p>Product not found</p>;
  return <h1>{data.product.name}</h1>;
}

Client Component

Use clientStorefront() for browser-side interactions like add-to-cart buttons.

components/add-to-cart-button.tsx

"use client";

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

export function AddToCartButton({
  cartId,
  productId,
  variantId,
}: {
  cartId: string;
  productId: string;
  variantId: string | null;
}) {
  async function handleClick() {
    const sdk = storefront.clientStorefront();
    await sdk.cart.addDeleteCartItem(
      { id: cartId },
      { product_id: productId, variant_id: variantId, quantity: 1 }
    );
  }

  return <button onClick={handleClick}>Add to Cart</button>;
}

SEO Metadata

generateMetadata runs at build time or request time without a live session — use publicStorefront().

app/products/[slug]/page.tsx

import type { Metadata } from "next";
import { storefront } from "@/lib/storefront";

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}): Promise<Metadata> {
  const { slug } = await params;
  const sdk = storefront.publicStorefront();
  const { data } = await sdk.catalog.getProductDetail({
    product_id_or_slug: slug,
  });

  const product = data?.product;
  if (!product) return { title: "Product Not Found" };

  return {
    title: product.name,
    description: product.short_description ?? undefined,
  };
}

Session Helpers

The storefront config accepts tokenStorageOptions to control cookie behavior:

Property	Default	Notes
`prefix`	`"ce_"`	Cookie name prefix
`maxAge`	`2592000` (30 days)	Cookie max-age in seconds
`path`	`"/"`	Available across all routes
`domain`	---	Defaults to request domain
`secure`	auto-detected	`true` in production (HTTPS)
`sameSite`	`"lax"`	CSRF protection

Client and server cookie configurations are automatically aligned — you do not need to configure them separately. For the full token lifecycle and returning-user flow, see Token Management.

Hosted Checkout + Next.js

If you use the Commerce Engine Hosted Checkout, follow this three-step pattern to keep the storefront SDK session and checkout session in sync. No provider wrapper is needed.

Add onTokensUpdated to Storefront Config

This callback forwards token updates from the storefront SDK to the checkout iframe.

lib/storefront.ts

import { Environment } from "@commercengine/storefront";
import { createNextjsStorefront } from "@commercengine/storefront/nextjs";

export const storefront = createNextjsStorefront({
  storeId: process.env.NEXT_PUBLIC_STORE_ID!,
  apiKey: process.env.NEXT_PUBLIC_API_KEY!,
  environment: Environment.Staging,
  tokenStorageOptions: { prefix: "myapp_" },
  onTokensUpdated: (accessToken, refreshToken) => {
    if (typeof window !== "undefined") {
      void import("@commercengine/checkout").then(({ getCheckout }) => {
        getCheckout().updateTokens(accessToken, refreshToken);
      });
    }
  },
});

Bootstrap + Init Checkout in a Root Client Component

Call both storefront.bootstrap() and initCheckout() in a single Client Component. The checkout is initialized with authMode: "provided" so the storefront SDK owns the session.

components/storefront-bootstrap.tsx

"use client";

import { useEffect } from "react";
import { initCheckout, destroyCheckout } from "@commercengine/checkout/react";
import { storefront } from "@/lib/storefront";

export function StorefrontBootstrap() {
  useEffect(() => {
    async function init() {
      await storefront.bootstrap();

      const sdk = storefront.clientStorefront();
      const accessToken = await sdk.getAccessToken();
      const refreshToken = await sdk.session.peekRefreshToken();

      initCheckout({
        storeId: process.env.NEXT_PUBLIC_STORE_ID!,
        apiKey: process.env.NEXT_PUBLIC_API_KEY!,
        authMode: "provided",
        accessToken: accessToken ?? undefined,
        refreshToken: refreshToken ?? undefined,
        onTokensUpdated: ({ accessToken, refreshToken }) => {
          void sdk.setTokens(accessToken, refreshToken);
        },
      });
    }

    init();
    return () => destroyCheckout();
  }, []);

  return null;
}

Mount in Root Layout

app/layout.tsx

import { StorefrontBootstrap } from "@/components/storefront-bootstrap";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <StorefrontBootstrap />
        {children}
      </body>
    </html>
  );
}

Then use useCheckout() in any Client Component — no provider needed:

components/cart-button.tsx

"use client";
import { useCheckout } from "@commercengine/checkout/react";

function CartButton() {
  const { cartCount, openCart, isReady } = useCheckout();
  return (
    <button onClick={openCart} disabled={!isReady}>Cart ({cartCount})</button>
  );
}

Migration from Deprecated Package

If you are migrating from @commercengine/storefront-sdk-nextjs, use this mapping:

Old (`storefront-sdk-nextjs`)	New (`storefront/nextjs`)
`@commercengine/storefront-sdk-nextjs`	`@commercengine/storefront/nextjs`
`createStorefront()`	`createNextjsStorefront({ storeId, apiKey, ... })`
`storefront.public()`	`storefront.publicStorefront()`
`storefront.session()` (client)	`storefront.clientStorefront()`
`storefront.session(await cookies())`	`await storefront.serverStorefront()`
`StorefrontSDKInitializer`	Custom `StorefrontBootstrap` component calling `storefront.bootstrap()`
Env var auto-inference	Explicit `storeId` and `apiKey` in config
`storefront({ isRootLayout: true })`	`storefront.publicStorefront()`
`NEXT_BUILD_CACHE_TOKENS` env flag	Not needed — use `publicStorefront()` for build-time reads

Common Pitfalls

Level	Issue	Solution
CRITICAL	Using `publicStorefront()` for cart, auth, or order flows	Use `await serverStorefront()` on the server or `clientStorefront()` on the client
CRITICAL	Using `clientStorefront()` on the server	`clientStorefront()` throws on the server — use `await storefront.serverStorefront()`
HIGH	Missing `StorefrontBootstrap` in root layout	Mount a Client Component calling `storefront.bootstrap()` in the root layout
HIGH	Calling `serverStorefront()` in a Client Component	Client Components must use `storefront.clientStorefront()`
HIGH	Using session accessors in SSG or root layout	Use `storefront.publicStorefront()` for build-time and root-layout reads
MEDIUM	Session-aware data in the root layout	Move it into a nested Server Component and use `await storefront.serverStorefront()`

Best Practices

One Config File

Create a single lib/storefront.ts that calls createNextjsStorefront() and export storefront from it. Import this everywhere.

Right Accessor, Right Context

publicStorefront() for public reads, serverStorefront() for session-aware server code, clientStorefront() for browser interactions.

Server Actions for Mutations

Auth, cart updates, and order creation should go through Server Actions using await serverStorefront() so cookies are read and written correctly.

Error Handling

Every SDK call returns { data, error }. Always check error before using data and implement error boundaries for graceful failures.

Cross-References

SDK Installation

Core SDK setup and framework detection guide.

Token Management

Full token lifecycle, cookie hydration, and returning-user flow.

Authentication Guide

OTP, email, and social login patterns for storefronts.

Hosted Checkout

Full hosted checkout integration with the React hook API.

Getting Started

Core Features

Framework Integration

Advanced Usage

NPM Package

@commercengine/storefront

Installation

Quick Start

Accessor Rules

Key Patterns

Public Server Component

Session-Aware Server Component

Server Actions (Mutations)

Static Site Generation (SSG)

Client Component

SEO Metadata

Session Helpers

Hosted Checkout + Next.js

Migration from Deprecated Package

Common Pitfalls

Best Practices

One Config File

Right Accessor, Right Context

Server Actions for Mutations

Error Handling

Cross-References

SDK Installation

Token Management

Authentication Guide

Hosted Checkout

​NPM Package

@commercengine/storefront

​Installation

​Quick Start

​Accessor Rules

​Key Patterns

​Public Server Component

​Session-Aware Server Component

​Server Actions (Mutations)

​Static Site Generation (SSG)

​Client Component

​SEO Metadata

​Session Helpers

​Hosted Checkout + Next.js

​Migration from Deprecated Package

​Common Pitfalls

​Best Practices

One Config File

Right Accessor, Right Context

Server Actions for Mutations

Error Handling

​Cross-References

SDK Installation

Token Management

Authentication Guide

Hosted Checkout

NPM Package

Installation

Quick Start

Accessor Rules

Key Patterns

Public Server Component

Session-Aware Server Component

Server Actions (Mutations)

Static Site Generation (SSG)

Client Component

SEO Metadata

Session Helpers

Hosted Checkout + Next.js

Migration from Deprecated Package

Common Pitfalls

Best Practices

Cross-References