Spree Storefront (Next.js)

The Spree Next.js storefront is a separate app that talks to the Spree backend over the v3 Store API (

/api/v3/store/*

) using

@spree/sdk

2.x.

create-spree-app

puts it in

apps/storefront/

(next to

server/

and

apps/dashboard/

); or fork https://github.com/spree/storefront. Next.js 16, React 19, Tailwind 4.

The storefront is optional — any frontend (Astro, Remix, React Native, …) can use the same Store API. This skill assumes the official storefront; the API contract is identical for any client.

Architecture — server-first

Browser → Server Action (src/lib/data/*) → @spree/sdk → Spree Store API
          httpOnly cookies (JWT, refresh token, cart token, country/locale) via src/lib/spree helpers

All API calls run server-side (Server Actions / Server Components in
```
src/lib/data/
```
). The browser never calls Spree directly; even the publishable key stays server-only (
```
SPREE_PUBLISHABLE_KEY
```
, no
```
NEXT_PUBLIC_
```
).
```
src/lib/spree/
```
holds the integration:
```
getClient()
```
, cookie helpers,
```
withAuthRefresh()
```
,
```
getLocaleOptions()
```
,
```
getCartOptions()
```
, middleware, surfaces (DTC vs wholesale), webhooks.
Client components (
```
CartContext
```
,
```
CheckoutContext
```
, …) hold UI state and call Server Actions — don't add SWR/React Query fetches against the Store API from the browser.

// src/lib/data/customer.ts (pattern)
import { getClient, withAuthRefresh, setAccessToken, setRefreshToken } from '@/lib/spree'

export async function login(email: string, password: string) {
  const { token, refresh_token, user } = await getClient().auth.login({ email, password })
  await setAccessToken(token)
  await setRefreshToken(refresh_token)
  return { success: true, user }
}

export async function getCustomer() {
  return withAuthRefresh((options) => getClient().customer.get(options))
}

Required env (

.env.local

SPREE_API_URL

SPREE_PUBLISHABLE_KEY

. Optional:

NEXT_PUBLIC_DEFAULT_COUNTRY

NEXT_PUBLIC_DEFAULT_LOCALE

NEXT_PUBLIC_SITE_URL

SPREE_WHOLESALE_CHANNEL

SPREE_WHOLESALE_PUBLISHABLE_KEY

SPREE_WEBHOOK_SECRET

RESEND_API_KEY

EMAIL_FROM

NEXT_PUBLIC_*

is only for values the browser genuinely needs (default region, Stripe/PayPal publishable keys).

@spree/sdk essentials

import { createClient } from '@spree/sdk'

const spree = createClient({
  baseUrl: process.env.SPREE_API_URL!,
  publishableKey: process.env.SPREE_PUBLISHABLE_KEY!,
  locale: 'en',          // sent as x-spree-locale (also per request: { locale })
  channel: 'online',     // sent as X-Spree-Channel; omit for the store default
})

const { data, meta } = await spree.products.list({ expand: ['media', 'default_variant'] })
const product = await spree.products.get('cool-shirt', { expand: ['variants', 'media'] })  // slug or prod_ id

const cart = await spree.carts.create()
await spree.carts.items.create(cart.id, { variant_id: 'variant_k5nR8xLq', quantity: 1 }, { spreeToken: cart.token })

const orders = await spree.customer.orders.list({}, { token })   // logged-in customer (JWT)

Flat responses (
```
product.name
```
); relations are
```
*_id
```
fields or, with
```
expand
```
, nested objects (
```
product.default_variant
```
,
```
product.primary_media
```
,
```
product.media[]
```
). Prices come as
```
Price
```
objects (
```
product.price.display_amount
```
) — never compute money client-side.
Auth modes: publishable key only (browsing) · +
```
spreeToken
```
(guest cart,
```
x-spree-token
```
) · +
```
token
```
JWT (customer). Types in
```
@spree/sdk
```
(also
```
@spree/sdk/zod
```
), webhook helpers in
```
@spree/sdk/webhooks
```
.
IDs are prefixed strings (
```
prod_
```
,
```
variant_
```
,
```
cart_
```
,
```
or_
```
,
```
cust_
```
,
```
ful_
```
). Carts use
cart.id
—
```
cart.number
```
is a deprecated mirror of
```
id
```
kept for 5.x clients (removed in 6.1).

Cart → checkout → order

Spree 6 splits the mutable Cart (

cart_…

) from the immutable Order (

or_…

) created when the cart completes. There is no checkout state machine to advance: you update the cart (email, addresses, delivery rate, payment) in any order, and the cart reports what's still missing.

const cart = await spree.carts.get(cartId, { spreeToken })
cart.requirements
// [{ step: 'address', field: 'ship_address', code: 'ship_address_required', message: '…' },
//  { step: 'delivery', field: 'delivery_method', code: 'delivery_method_required', message: '…' }, …]

requirements[]

entries are

{ step, field, code, message }

. Codes include

line_items_required

email_required

ship_address_required

delivery_method_required

payment_required

po_number_required

guest_checkout_not_allowed

quantity_rule_violated

order_minimum_not_met

discontinued

out_of_stock

. Steps (

cart

address

delivery

payment

) are advisory UI grouping — map them to checkout sections and show

message

. Completion is the only hard gate. Custom requirements come from the backend (

Spree::Checkout::Registry.add_requirement

, see

spree-checkout

Delivery:

spree.carts.fulfillments.update(cartId, fulfillmentId, { selected_delivery_rate_id }, opts)

returns the recalculated cart.

Payment (session-based gateways — Stripe, Adyen, PayPal):
1. ```
spree.carts.paymentSessions.create(cartId, { payment_method_id }, opts)
```
  → provider data (client secret, drop-in token, redirect URL).
2. Render the provider UI / redirect.
3. ```
spree.carts.paymentSessions.complete(cartId, sessionId, { session_result }, opts)
```
  .
4. ```
spree.carts.complete(cartId, opts)
```
  → returns the Order (typed
```
Order | OrderGroup
```
  — a multi-seller marketplace cart returns an
```
ogrp_…
```
  group; narrow with
```
isOrderGroup
```
  from
```
@spree/sdk
```
  ). It's idempotent: if a gateway webhook already completed the cart, it returns the existing result. Non-session methods (check, COD, bank transfer):
```
spree.carts.payments.create(...)
```
  .
After completion, the cart is gone from
```
carts.get
```
— read the result with spree.orders.get(id, params, { spreeToken | token })
. It accepts the
```
or_…
```
id or the original
```
cart_…
```
id, so the confirmation page (
```
order-placed/[id]
```
) can keep using the cart id as its handle. Order
```
status
```
is
```
draft
```
/
```
placed
```
/
```
canceled
```
, with separate
```
payment_status
```
and
```
fulfillment_status
```
.

Reference flows:

src/lib/data/checkout.ts

payment.ts

(

completeCheckoutOrder

also tolerates 403/422 races),

components/checkout/*

, and the gateway gems (e.g.

spree_stripe

Multi-region URLs

Every route lives under

src/app/[country]/[locale]/…

(

/us/en/products

/de/de/products

), mapped to a Spree Market (country + currency + locale).

src/proxy.ts

(Next 16's middleware file) wires

createSpreeMiddleware({ defaultCountry, defaultLocale, staticRoutes? })

from

@/lib/spree/middleware

, which:

redirects bare paths to
```
/{country}/{locale}/…
```
;
detects country from the
```
spree_country
```
cookie →
```
x-vercel-ip-country
```
/
```
cf-ipcountry
```
→ default, and locale from
```
spree_locale
```
→
```
Accept-Language
```
→ default;
syncs the
```
spree_country
```
/
```
spree_locale
```
cookies with the URL.

Data functions don't take region args — they call

getLocaleOptions()

, which reads those cookies and passes locale/country to the SDK. New pages go under

src/app/[country]/[locale]/(storefront)/your-page/page.tsx

to inherit the layout.

CountrySwitcher

changes region by navigating to a new prefix.

Wholesale / channel surfaces

/wholesale

is an opt-in B2B portal on a separate channel, enabled only when

SPREE_WHOLESALE_CHANNEL

is set to a gated channel's code (unset → all wholesale UI hidden, routes 404). A surface = a channel-bound SDK client (

channel: 'wholesale'

→

X-Spree-Channel

) with its own cart cookie and cache tags; the customer JWT is shared. The channel's

storefront_access

(

login_required

prices_hidden

public

) is enforced by the API (401, or money fields

null

); buyer approval = membership in the Wholesale customer group; trade prices come from backend price lists. Treat it as a reference you can adapt (members-only DTC, B2B-only store) — see

spree-b2b

Webhooks and transactional emails

The storefront can own customer emails (react-email templates in

src/lib/emails/

, sent via Resend; written to

.next/emails/

in dev; preview at

/dev/emails

). The route

src/app/api/webhooks/spree/route.ts

uses

createWebhookHandler

from

@/lib/spree/webhooks

, which verifies

X-Spree-Webhook-Signature

(HMAC-SHA256 over

"{timestamp}.{body}"

, timing-safe, 5-minute replay window) and dispatches by event name:

import { createWebhookHandler } from '@/lib/spree/webhooks'

const handler = createWebhookHandler({
  secret: process.env.SPREE_WEBHOOK_SECRET!,
  handlers: {
    'order.placed': handleOrderPlaced,
    'order.canceled': handleOrderCanceled,
    'order.fulfilled': handleOrderFulfilled,        // or 'fulfillment.fulfilled' for per-parcel emails
    'customer.password_reset_requested': handlePasswordReset, // must be subscribed by name — `*` never receives it
  },
  // waitUntil, toleranceSeconds optional
})
export const POST = handler

Event names are Spree 6's: order.placed
(not
```
order.completed
```
), order.fulfilled
/
```
fulfillment.fulfilled
```
(not
```
order.shipped
```
). The shipped storefront code still registers
```
order.completed
```
and
```
order.shipped
```
— deprecated aliases Spree 6.0 still sends alongside the new names and stops sending in 6.1. Switch handlers and endpoint subscriptions to the new names.
Marketplace (split) checkouts: child orders publish
```
order.placed
```
with
```
notify_customer: false
```
; the purchase's confirmation belongs to
```
order_group.completed
```
— add a handler for it if you send order emails (see
```
spree-marketplace
```
).
When the storefront owns customer emails, turn off Spree's own with the store preference
```
send_consumer_transactional_emails
```
(false) so customers don't get two. That switch (and
```
notify_customer: false
```
on an order) only silences customer emails — the store's new-order notification to
```
new_order_notifications_email
```
still goes out whenever that address is set.
Create the endpoint in the dashboard under Settings → Developer → Webhooks, subscribe to the events, and copy its secret into
```
SPREE_WEBHOOK_SECRET
```
. For local testing expose the storefront (
```
cloudflared tunnel --url http://localhost:3001
```
).
Failed deliveries are retried with backoff (5 attempts over about six minutes, same event
```
id
```
), and an endpoint is disabled after 15 consecutive failed deliveries — return 2xx quickly, dedupe on
```
event.id
```
, and do slow work in
```
waitUntil
```
/a queue. Unhandled events return 200
```
{ handled: false }
```
.

Outside the official storefront, use

verifyWebhookSignature(body, signature, timestamp, secret)

and

type WebhookEvent<T>

from

@spree/sdk/webhooks

. Full event list:

spree-events-webhooks

Testing

Unit/integration: Vitest —
```
pnpm test
```
/
```
pnpm test:watch
```
(tests live next to code, e.g.
```
src/lib/data/__tests__
```
).
E2E: Playwright against a real backend in Docker: export a matching Stripe test key pair (
```
STRIPE_PUBLISHABLE_KEY
```
,
```
STRIPE_SECRET_KEY
```
),
```
pnpm e2e:up
```
(boots Postgres/Redis +
```
ghcr.io/spree/spree:latest
```
, seeds via
```
@spree/cli
```
, writes
```
.env.e2e
```
),
```
pnpm test:e2e
```
(
```
:ui
```
for interactive),
```
pnpm e2e:down
```
.

Test against your backend:

SPREE_IMAGE=<image> pnpm e2e:up

. In a

create-spree-app

project build it from the root with

docker build . -f server/Dockerfile -t project-spree:e2e

first; generated CI does this for you.

Storefront vs backend — where does the change belong

Want to…	Belongs in
Layout, copy, styling, a new content page	Storefront ( `src/app/[country]/[locale]/(storefront)/…` , `@theme` tokens in `src/app/globals.css` )
Add a field to product/cart responses	Backend — model + serializer swap ( `spree-resource` , `spree-api-v3` )
Change pricing	Backend — price lists / rules ( `spree-pricing` )
Change how cart totals are calculated	Backend — `Spree::Carts::RecalculateTotals` (DI key `cart_recalculate_totals_workflow` ) or a workflow hook ( `spree-order-totals` , `spree-workflows` )
Add a checkout requirement (e.g. "accept terms")	Backend `Spree::Checkout::Registry.add_requirement` ; storefront renders the new `requirements[]` code
Add a country / currency / language	Backend Markets; storefront just follows the URL + cookies
Customize the checkout UI	Storefront ( `components/checkout/*` )
A/B test the PDP, client analytics	Storefront ( `src/lib/analytics` )
Sync orders to a CRM/ERP	Backend subscriber on `order.placed` ( `spree-events-webhooks` )
Customer email look & feel	Storefront emails (webhooks) or backend mailers — pick one owner

Rule: anything customer-visible is storefront; anything that touches data, money, or business rules is backend, so every frontend gets the same behavior.

Gotchas

Secret keys (
sk_…
) never go in a storefront — not even server-side; the Store API uses publishable keys. Admin tasks belong in the dashboard or a backend job.
Cart tokens grant cart access — keep them in httpOnly, secure cookies (the helpers do).
Cache catalog, never carts/checkout. The storefront uses Next cache tags per surface (
```
updateTag(cartTag(surface))
```
) — invalidate after cart mutations.
Don't assume a checkout step order — drive the UI from
```
requirements[]
```
, and handle
```
carts.complete
```
returning an error (code
```
cart_cannot_complete
```
) by re-reading the cart's
```
requirements
```
.
Don't call
carts.get
after completion — use
```
orders.get
```
with the cart or order id.
Localization is header-driven (
```
x-spree-locale
```
,
```
X-Spree-Channel
```
), not
```
Accept-Language
```
; the storefront gets it from the URL segments via cookies.
Stay on the upstream track: add the storefront repo as an
```
upstream
```
remote and merge periodically; keep customizations in components/data files you own.

Where to read further

Docs (installed):

node_modules/@spree/docs/dist/developer/storefront/nextjs/{architecture,customization,multi-region,wholesale,emails,environment-variables,testing,deployment,wallet-payments}.md

; SDK:

developer/sdk/quickstart.md

. Online: https://spreecommerce.org/docs/developer/storefront/nextjs/architecture

Tutorial:
```
developer/tutorial/storefront.md
```

Source: https://github.com/spree/storefront (

src/lib/spree/

src/lib/data/

src/app/api/webhooks/spree/route.ts

)

Related skills:

spree-typescript-sdk

spree-api-v3

spree-checkout

spree-events-webhooks

spree-b2b

spree-i18n

spree-deployment

spree-storefront

NPX Install

SKILL.md Content

Spree Storefront (Next.js)

Architecture — server-first

@spree/sdk essentials

Cart → checkout → order

Multi-region URLs

Wholesale / channel surfaces

Webhooks and transactional emails

Testing

Storefront vs backend — where does the change belong

Gotchas

Where to read further