Storefront

The storefront is the customer-facing shop, built on the Next.js App Router with React Server Components. It is early access, see Status. Every route lives under a country segment (/{country}/...), and the middleware resolves country, language, currency and channel from it before the page renders.

What It Covers

Catalog, search, cart, checkout and the customer account. It uses these backend APIs: Matrix v2, Checkout v2, Accounts v1 and ContentDB v1. The path from a product to an order, across the backend and the storefront: Commerce Journey.

Stack

Layer	Choice
Framework	Next.js (App Router, React Server Components)
UI	React, Tailwind CSS, shadcn/ui
Server state	TanStack Query
Client state	Zustand
Forms	React Hook Form + Zod
Package manager	pnpm

Run It Locally

From the Docker harness (entirius-zeno), make pwa builds the image from the GitHub repo and serves it on http://localhost:3100/. Its configuration is baked in when the image is built, so after changing SERVICE_PORT, PWA_CHANNEL or CHECKOUT_API_KEY in .env, run make pwa again.

On its own, from a clone of the repo:

cp -r _CONFIG.example _CONFIG
pnpm install
pnpm dev

Configuration

_CONFIG/ is not committed and the build fails without it. pnpm build bakes it in, so a changed value needs a new build. It holds three files:

File	Keys
_CONFIG/app.config.json	API_BASE_URL (backend URL), DEBUG_MODE
_CONFIG/channels.config.json	per channel: CHANNEL_LABEL, API_CHECKOUT_KEY
_CONFIG/countries.config.json	per country: languages, currencies, channels and their defaults

API_BASE_URL must be reachable both from the Next.js server and from the browser. API_CHECKOUT_KEY is the checkout x-api-key your backend issues for that channel.

Documentation

Read these on GitHub:

• README
• AGENTS.md
• docs/architecture.md
• docs/configuration.md
• docs/search.md

Next

Status