@spree/docs 0.1.131 → 0.1.133

package/dist/developer/storefront/nextjs/multi-region.md

@@ -0,0 +1,75 @@
+---
+title: Multi-Region
+description: How the Spree Next.js Storefront serves multiple countries, currencies, and languages from a single deployment via URL segments and edge middleware
+---
+
+The storefront serves multiple countries, currencies, and languages from a single deployment. Region is encoded in the URL, detected automatically for first-time visitors by middleware, and mapped to a [Spree Market](../../core-concepts/markets.md) — the model that bundles a country, currency, and locale — so every server-side fetch resolves prices and content for the right region.
+
+## URL structure
+
+Every route is prefixed with a country and locale segment:
+
+```
+/us/en/products          # US market, English
+/de/de/products          # German market, German
+/uk/en/products          # UK market, English
+```
+
+The `[country]` and `[locale]` segments are the first two dynamic params of the App Router tree (`src/app/[country]/[locale]/…`). Because region lives in the path, every URL is shareable and independently cacheable, and search engines index each region separately.
+
+## The middleware
+
+A visitor who lands on a bare path (no region prefix) is redirected to the correct `/{country}/{locale}/…` URL by an edge middleware. It's wired in `src/proxy.ts`:
+
+```typescript
+import { createSpreeMiddleware } from '@/lib/spree/middleware'
+import { getDefaultCountry, getDefaultLocale } from '@/lib/store'
+
+export const proxy = createSpreeMiddleware({
+  defaultCountry: getDefaultCountry(),
+  defaultLocale: getDefaultLocale(),
+})
+
+export const config = {
+  matcher: ['/((?!api/|_next/static|_next/image|favicon.ico|.*\\..*$).*)'],
+}
+```
+
+`createSpreeMiddleware` (from `src/lib/spree`) does three things:
+
+- **Redirects** bare paths to `/{country}/{locale}/…`.
+- **Detects** the visitor's country and locale (see below).
+- **Syncs** `spree_country` and `spree_locale` cookies with the URL segments, so server-side fetches via `getLocaleOptions()` resolve the same market the URL asks for.
+
+Requests that already carry a `/{country}/{locale}` prefix pass through untouched — the middleware only refreshes the cookies to match.
+
+### Detection chain
+
+For a request without a region prefix, each value is resolved from the first source that has it:
+
+| Value | Resolution order |
+|-------|------------------|
+| **Country** | `spree_country` cookie → `x-vercel-ip-country` / `cf-ipcountry` geo header → default |
+| **Locale** | `spree_locale` cookie → `Accept-Language` header (primary tag) → default |
+
+Geo headers are set by the hosting edge — `x-vercel-ip-country` on Vercel, `cf-ipcountry` behind Cloudflare. On a host that provides neither, detection falls back to `Accept-Language` for locale and the configured default for country. A returning visitor's cookie always wins, so a manual region change sticks.
+
+### Configuration
+
+`createSpreeMiddleware` accepts:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `defaultCountry` | Fallback country ISO when nothing else matches | `us` |
+| `defaultLocale` | Fallback locale when nothing else matches | `en` |
+| `staticRoutes` | Path prefixes to skip | `['/_next', '/api', '/dev', '/favicon.ico']` |
+
+In the storefront these defaults come from `NEXT_PUBLIC_DEFAULT_COUNTRY` and `NEXT_PUBLIC_DEFAULT_LOCALE` (see [Environment Variables](environment-variables.md)). The `matcher` in `proxy.ts` additionally excludes API routes, Next.js internals, and any path with a file extension, so the middleware only runs on page navigations.
+
+## Switching regions
+
+The `CountrySwitcher` component (in `src/components/layout/`) lets a visitor change region manually. Selecting a new region navigates to the matching URL prefix; the middleware then updates the `spree_country` / `spree_locale` cookies so the choice persists across future visits.
+
+## How region reaches the data layer
+
+Region-aware reads don't take a country/locale argument — they call `getLocaleOptions()` from `src/lib/spree`, which reads the `spree_country` / `spree_locale` cookies the middleware keeps in sync with the URL. That value is passed to `@spree/sdk`, which sends it to the Store API so prices, currency, and translated content come back for the right [market](../../core-concepts/markets.md). See [Architecture](architecture.md) for the wider server-first data flow.

package/dist/developer/storefront/nextjs/quickstart.md

@@ -34,19 +34,19 @@ The [Spree Storefront](https://github.com/spree/storefront) is a production-read
 
 ## Installation
 
-### Option 1: Fork the Repository (Recommended)
+### Recommended: create-spree-app
 
-Fork the repository on GitHub, then clone your fork:
+The fastest way to get a full project — Spree backend, this Next.js storefront, and the `spree` CLI, wired together — is [`create-spree-app`](../../create-spree-app/quickstart.md):
 
 ```bash
-git clone https://github.com/YOUR_USERNAME/storefront.git
-cd storefront
-npm install
+npx create-spree-app my-store
 ```
 
-This gives you a full copy you can customize freely while still being able to pull upstream updates.
+The storefront is included by default (pass `--no-storefront` to skip it). It's scaffolded into `apps/storefront/` with its `.env.local` already pointing at the backend, so it boots against real data with no manual key wiring.
+
+### Standalone
 
-### Option 2: Clone Directly
+To run the storefront on its own — against an existing Spree backend, or to work on the storefront repo directly — clone it and install:
 
 ```bash
 git clone https://github.com/spree/storefront.git
@@ -54,6 +54,8 @@ cd storefront
 npm install
 ```
 
+Then follow [Configuration](#configuration) to point it at your Spree API. If you plan to customize and track upstream changes, [fork first](customization.md#tracking-upstream-updates).
+
 ## Configuration
 
 Copy the environment file:
@@ -81,6 +83,8 @@ npm run dev
 
 Open [http://localhost:3001](http://localhost:3001) in your browser.
 
+> **NOTE:** Testing Apple Pay / Google Pay locally needs a public HTTPS URL. See [Wallet Payments in Development](wallet-payments.md).
+
 ## Production Build
 
 ```bash

package/dist/developer/storefront/nextjs/testing.md

@@ -0,0 +1,81 @@
+---
+title: Testing
+description: Run the Spree Next.js Storefront's unit tests with Vitest and its end-to-end suite with Playwright against a real Spree backend
+---
+
+The storefront ships two test layers: fast unit/integration tests with Vitest, and a browser end-to-end suite with Playwright that runs against a real Spree backend booted in Docker.
+
+## Unit & integration (Vitest)
+
+```bash
+npm test            # one-shot
+npm run test:watch  # watch mode
+```
+
+## End-to-end (Playwright)
+
+The E2E suite drives a browser against a real Spree backend. `npm run e2e:up` boots the backend — Postgres, Redis, and the official `ghcr.io/spree/spree:latest` image from `e2e-backend/docker-compose.yml` — then seeds it and mints an API key through the official [`@spree/cli`](../../cli/quickstart.md) (`spree seed`, `spree sample-data`, `spree api-key create`), installed as a dev dependency. No `create-spree-app` setup is required.
+
+```bash
+# 1. Export a Stripe test-mode key pair from your own Stripe sandbox.
+#    Both keys must belong to the same account — Stripe no longer
+#    publishes a working sample secret key, and a mismatched pair makes
+#    the checkout payment step fail.
+export STRIPE_PUBLISHABLE_KEY=pk_test_…
+export STRIPE_SECRET_KEY=sk_test_…
+
+# 2. Boot Spree + Postgres + Redis, seed sample data, register a Stripe
+#    payment gateway, mint a publishable key, and write .env.e2e.
+npm run e2e:up
+
+# 3. Run the suite. Playwright boots `next dev` against .env.e2e.
+npm run test:e2e
+
+# Optional: interactive UI mode.
+npm run test:e2e:ui
+
+# Tear everything down.
+npm run e2e:down
+```
+
+The checkout test pays with card `4242 4242 4242 4242` through Stripe's [test mode](https://docs.stripe.com/keys). PaymentIntents land in whichever Stripe test account owns the keys you exported.
+
+### CI
+
+In CI, set `STRIPE_SECRET_KEY` as a repository secret and `STRIPE_PUBLISHABLE_KEY` as a repository variable (**Settings → Secrets and variables → Actions**). The E2E job skips itself on fork PRs, where GitHub never exposes repository secrets.
+
+## Testing against a customized backend
+
+> **NOTE:** By default the E2E suite runs against the stock official Spree image (`ghcr.io/spree/spree:latest`), so it verifies the storefront against a **vanilla Spree** — not a backend with your own extensions, serializers, or seed data.
+
+The E2E stack reads a `SPREE_IMAGE` env var and falls back to the stock image when it's unset. Set it to any image that exposes the Store API on the container's port `3000`, and the suite runs against that backend instead.
+
+### Your own Spree image
+
+If you already publish a customized Spree image:
+
+```bash
+SPREE_IMAGE=ghcr.io/your-org/your-spree:latest npm run e2e:up
+npm run test:e2e
+```
+
+### A `create-spree-app` project's backend
+
+A project scaffolded with [`create-spree-app`](../../create-spree-app/quickstart.md) has its customizable Spree in `backend/` (built from `backend/Dockerfile`) and this storefront in `apps/storefront/`. Build that backend into a local image and point the suite at it — this is what tests the storefront against the **exact Spree you deploy**, extensions and all:
+
+```bash
+# From the project root — build the customized backend image
+docker build -t project-spree:e2e ./backend
+
+# From apps/storefront — run E2E against it
+cd apps/storefront
+SPREE_IMAGE=project-spree:e2e npm run e2e:up
+npm run test:e2e
+npm run e2e:down
+```
+
+> **NOTE:** New `create-spree-app` projects wire this into the generated storefront CI workflow automatically — the workflow builds `backend/Dockerfile` and runs the storefront E2E against that image rather than stock Spree.
+
+### Interactive / manual
+
+To click through the storefront against a running backend (no E2E harness), point it there directly: set `SPREE_API_URL` and `SPREE_PUBLISHABLE_KEY` in `.env.local` (see [Environment Variables](environment-variables.md)) and run `npm run dev`.

package/dist/developer/storefront/nextjs/wallet-payments.md

@@ -0,0 +1,52 @@
+---
+title: Wallet Payments in Development
+description: Test Apple Pay and Google Pay against a local Spree Next.js Storefront using a public HTTPS URL
+---
+
+Apple Pay and Google Pay require HTTPS **and a publicly-reachable URL** — Stripe verifies the payment method domain from the internet, so `localhost` and locally-trusted certificates (e.g. `mkcert` + `lvh.me`) won't pass domain verification. The simplest way to expose your local storefront with a valid public HTTPS URL is [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/).
+
+## Setup
+
+1. Install `cloudflared`:
+
+   ```bash
+   brew install cloudflared
+   ```
+
+2. Start the dev server normally (HTTP on port 3001):
+
+   ```bash
+   npm run dev
+   ```
+
+3. In a second terminal, expose it through a quick tunnel:
+
+   ```bash
+   cloudflared tunnel --url http://localhost:3001
+   ```
+
+   The output will contain a URL like `https://<random-words>.trycloudflare.com`.
+
+4. Register that URL in your [Stripe Payment method domains](https://dashboard.stripe.com/settings/payment_methods/domains).
+
+5. Open the tunnel URL in your browser and test the Express Checkout buttons in the cart.
+
+## Stable tunnel URLs
+
+`next.config.ts` already allows `*.trycloudflare.com` via `allowedDevOrigins`, so quick tunnels work out of the box. Every time you restart `cloudflared tunnel --url ...` you get a new random subdomain — if you need a stable URL (to avoid re-registering in Stripe on each run), set up a [named tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/#using-named-tunnels) on your own domain.
+
+## The Spree backend must also be publicly reachable
+
+The storefront's server-side fetches go to `SPREE_API_URL`, but image URLs and a few other backend-served paths (e.g. the Apple Pay domain-verification file under `/.well-known/apple-developer-merchantid-domain-association`) are fetched by the browser directly and must resolve from the public internet.
+
+Point `SPREE_API_URL` at a hosted Spree (e.g. `*.spree.sh`, `*.vendo.dev`, your own staging) or expose your local Spree with another tunnel:
+
+```bash
+cloudflared tunnel --url http://localhost:3000
+```
+
+When tunneling a local Rails app, allow the tunnel host in the backend's `.env`:
+
+```env
+RAILS_DEVELOPMENT_HOSTS=.trycloudflare.com
+```

package/dist/developer/storefront/nextjs/wholesale.md

@@ -0,0 +1,82 @@
+---
+title: Wholesale Portal
+description: The opt-in B2B wholesale surface and how channel-backed surfaces work
+---
+
+## What the Wholesale Portal Is
+
+The storefront ships an optional **wholesale portal** at `/wholesale` — a gated B2B surface for approved trade buyers. It runs on a separate Spree sales channel but shares the same storefront app and Spree backend as the public direct-to-consumer (DTC) store, so a single deployment serves both audiences: the open catalog for shoppers and a login-gated trade catalog with volume pricing for wholesale buyers.
+
+The portal is an **opt-in addon**. It is off by default; a DTC-only storefront never renders any wholesale UI.
+
+> **NOTE:** The wholesale portal is a **reference implementation**, not a fixed feature. It demonstrates one shape — a gated B2B surface running *alongside* an open DTC store — but the same building blocks (channels, [surfaces](#surfaces-and-channel-switching), and [access gating](#gating-modes)) support the whole spectrum. You can invert the default and make the storefront closed or limited: gate the *primary* DTC channel with `login_required` or `prices_hidden` for a members-only or invite-only shop, drop the public catalog entirely and ship a login-first B2B storefront, or run several gated channels with no open surface at all. Treat this page as a worked example to adapt, not a prescription — the storefront is yours to reshape.
+
+## Surfaces and Channel Switching
+
+A **surface** is a distinct sales context backed by its own Spree [channel](../../core-concepts/channels.md). The storefront models two out of the box — `dtc` (the public storefront) and `wholesale` (the trade portal) — but the mechanism is general: any channel on your backend can back its own surface.
+
+The surface selects which SDK client a request goes through. A channel-bound client sends the channel code on every request via the `X-Spree-Channel` header, and the Store API [resolves the request against that channel](../../core-concepts/channels.md#resolution-at-request-time) — its catalog, pricing, and access rules. In the SDK this is the `channel` client option:
+
+```ts
+import { createClient } from '@spree/sdk'
+
+const wholesaleClient = createClient({
+  baseUrl: process.env.SPREE_API_URL,
+  publishableKey: process.env.SPREE_PUBLISHABLE_KEY,
+  channel: 'wholesale', // sent as X-Spree-Channel on every request
+})
+```
+
+Alternatively, a **channel-bound publishable key** carries the channel server-side: when a key is scoped to a channel on the backend, the API assigns that channel to the request without needing the header. Either path works; the header is the simplest and is what the storefront uses by default.
+
+Because each surface has its own client, cart cookies, and cache keys, a customer can hold an open DTC cart and an open wholesale cart at the same time without them mixing. The customer session (JWT) is shared — it's the same person signing in — so only the cart splits, never the auth.
+
+To add your own channel-backed surface, follow the same pattern: create the channel on the backend, add a client bound to its code, and thread the surface through the routes that should target it.
+
+## Enabling Wholesale
+
+Wholesale turns on through a single environment variable:
+
+- **`SPREE_WHOLESALE_CHANNEL`** — the enable switch. Set it to the code of a gated channel on your backend (e.g. `wholesale`). There is **no default**: when it is unset, the storefront runs DTC-only — the wholesale nav link, footer link, and homepage section are hidden, and every `/wholesale` route returns 404.
+- **`SPREE_WHOLESALE_PUBLISHABLE_KEY`** — optional. The channel header alone selects the channel, so this falls back to `SPREE_PUBLISHABLE_KEY`. Set it only to bind a channel-scoped publishable key.
+
+The backend must have a [channel](../../core-concepts/channels.md) whose code matches `SPREE_WHOLESALE_CHANNEL`. Its [`storefront_access`](../../core-concepts/channels.md#storefront-access-gating) posture decides how much a guest can see — the portal supports both `login_required` (guests are walled off entirely) and `prices_hidden` (guests browse the catalog but not prices). See [Gating Modes](#gating-modes) below. Spree installs seed a `login_required` wholesale channel by default; switching to `prices_hidden` is a single flag on that same channel — no new channel or seed data.
+
+## How Gating Works End to End
+
+Two independent checks gate the portal — one at the **channel** (how much of the catalog a guest may see), one at the **customer** (whether a buyer may transact at trade pricing). The channel check is set by the channel's [gating mode](#gating-modes); the customer check is always the same.
+
+**Channel access** is enforced by the Store API, not the storefront — the storefront can't loosen it. Depending on the channel's `storefront_access` posture, a guest is either rejected outright (`login_required`) or served the catalog with money fields returned as `null` (`prices_hidden`). This is a general channel feature; see [Channels → Storefront Access Gating](../../core-concepts/channels.md#storefront-access-gating) for how it's resolved and enforced.
+
+**Buyer approval.** Being logged in isn't enough; a buyer must be *approved*. Approval is membership in the **Wholesale** [customer group](../../core-concepts/pricing.md#customer-group-rule) — an admin adds an applicant to the group to approve them. The storefront reads `customer_groups` on `customers/me` and branches accordingly:
+
+- **Guest** — sees the sign-in / apply wall (`login_required`), or the read-only catalog with sign-in-for-pricing prompts (`prices_hidden`).
+- **Signed in, not in the group** — sees an application-pending state. Signing in never skips approval: an authenticated but unapproved buyer cannot transact under either mode.
+- **Signed in and in the group** — gets the full portal: trade catalog, quick order, and the wholesale cart.
+
+**Trade pricing** is unlocked by volume. The seeded model grants a trade price once a line reaches a minimum quantity of the same item (10 or more per item in the sample data). The applicable volume rule lives on a backend [Price List](../../core-concepts/pricing.md#price-lists); the storefront surfaces the trade price the API returns for a qualifying quantity.
+
+## Gating Modes
+
+A channel's `storefront_access` posture is one of three values. The wholesale portal supports the two gated modes; the third describes a fully public channel like DTC.
+
+| Mode | Guest sees catalog | Guest sees prices | Guest can order |
+|---|---|---|---|
+| `login_required` | No — hard `401`, sign-in wall | No | No |
+| `prices_hidden` | Yes — read-only | No — "sign in for pricing" | No — "sign in to order" |
+| `public` | Yes | Yes | Yes (subject to guest checkout) |
+
+**`login_required`** is the strictest posture and the seeded default. The Store API rejects any unauthenticated request to the channel with `401`, so a guest can't read wholesale catalog or pricing at all. The storefront shows the sign-in / apply wall in place of every gated page.
+
+**`prices_hidden`** opens the catalog to guests while keeping pricing private. The channel doesn't reject unauthenticated requests, but the API serializes every money field as `null` for a guest. In the portal, a guest browses the catalog and product pages read-only: each price renders a **"sign in for pricing"** prompt, and add-to-cart becomes **"sign in to order."** Ordering surfaces (cart, quick order) still require sign-in — a guest is redirected to the sign-in flow rather than shown an empty wholesale cart. Approval is unchanged: signing in reveals list prices, and joining the Wholesale group unlocks trade pricing. This mode suits a trade catalog you want discoverable (for SEO or lead generation) without exposing negotiated pricing.
+
+**`public`** is an ungated channel — the posture the DTC store runs on. It's listed here for completeness; a wholesale channel would not normally use it.
+
+Switching a wholesale channel between the two supported modes is a single change to [`storefront_access`](../../core-concepts/channels.md#storefront-access-gating) on the backend — set on the channel, or inherited from the [store's default](../../core-concepts/stores.md#storefront-access-defaults). Nothing in the storefront needs redeploying — the portal reads the channel's posture at request time and adapts. Login and signup always run through the same approval flow regardless of mode.
+
+## Related Documentation
+
+- [Channels](../../core-concepts/channels.md) — The sales channel that backs the wholesale surface, and the general [Storefront Access Gating](../../core-concepts/channels.md#storefront-access-gating) mechanism the portal builds on
+- [Stores](../../core-concepts/stores.md) — Store-level [defaults](../../core-concepts/stores.md#storefront-access-defaults) that channels inherit
+- [Pricing](../../core-concepts/pricing.md) — [Price Lists](../../core-concepts/pricing.md#price-lists) and the [Customer Group Rule](../../core-concepts/pricing.md#customer-group-rule) behind approval and trade pricing
+- [Store SDK: Configuration](../../sdk/configuration.md) — `setChannel` and the channel client option used to bind a surface

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.131",
+  "version": "0.1.133",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",