@spree/docs 0.1.131 → 0.1.133

package/dist/developer/core-concepts/channels.md

@@ -20,6 +20,8 @@ Every store ships with one default channel named *Online Store*. You can add mor
 | `code` | URL-safe slug, stable identifier sent via the `X-Spree-Channel` header | `pos` |
 | `active` | When `false`, the channel stops accepting orders | `true` |
 | `default` | Exactly one channel per store is the default. Used as a fallback when no channel header is present and as the auto-publish target for new products | `true` |
+| `storefront_access` | Controls what an anonymous visitor may see: `public`, `prices_hidden`, or `login_required`. Unset inherits the store's setting. See [Storefront Access Gating](#storefront-access-gating) | `login_required` |
+| `guest_checkout` | Whether an order may be placed without an account on this channel. Unset inherits the store's setting | `false` |
 | `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](shipments.md#order-routing) strategy | `Spree::OrderRouting::Strategy::Rules` |
 
 `code` is normalized to a URL-safe slug on save — `POS` becomes `pos`, `Point of Sale!` becomes `point-of-sale`. Leaving `code` blank derives it from `name`.
@@ -89,6 +91,52 @@ Every order is attributed to one channel. The channel is set from the `X-Spree-C
 
 This attribution drives reporting (best-selling by channel, revenue per channel) and per-channel order routing — see [Order Routing](shipments.md#order-routing).
 
+### Storefront Access Gating
+
+
+A channel's `storefront_access` decides what an **anonymous** visitor — a request with no authenticated customer — may see. Logged-in customers are never gated. The posture is one of three values:
+
+| Mode | Guest sees catalog | Guest sees prices | Use case |
+|---|---|---|---|
+| `public` | Yes | Yes | The default. An open storefront — anyone can browse; guests can also check out when `guest_checkout` is enabled. |
+| `prices_hidden` | Yes | No — prices come back `null` | A catalog you want discoverable, with pricing revealed only after sign-in (e.g. a trade catalog for lead generation). |
+| `login_required` | No — reads rejected with `401` | No | A fully gated surface — a guest can't read the catalog at all (e.g. a members-only or B2B wholesale portal). |
+
+The gate is enforced by the **Store API**, not the storefront, so a storefront app can't loosen it:
+
+- **`login_required`** — every gated read returns `401` for an unauthenticated request. Endpoints that must stay reachable before sign-in (authentication, password reset, reference data like countries and currencies) are exempt.
+- **`prices_hidden`** — reads succeed, but every money field is serialized as `null` for a guest. The storefront renders these as a sign-in prompt rather than a price.
+
+A companion control, **`guest_checkout`**, decides whether an order can be placed without an account on the channel. It's independent of `storefront_access` — a `public` channel can still require accounts, and the two are resolved separately.
+
+#### Store fallback
+
+Both controls fall back to the owning [Store](stores.md) when the channel's own value is unset — the same inheritance pattern as the channel's order-routing strategy. `storefront_access` resolves to the channel value, then the store value, and finally `public` when neither is set. This lets you set a store-wide default (e.g. "all channels require login") and override per channel where needed.
+
+
+```typescript Admin SDK
+// Gate a channel behind sign-in, and require accounts at checkout
+await adminClient.channels.update('ch_wholesale', {
+  storefront_access: 'login_required',
+  guest_checkout: false,
+})
+
+// Clear the channel value to inherit the store's default
+await adminClient.channels.update('ch_wholesale', {
+  storefront_access: null,
+})
+```
+
+```bash cURL
+curl -X PATCH 'https://api.mystore.com/api/v3/admin/channels/ch_wholesale' \
+  -H 'X-Spree-API-Key: sk_xxx' \
+  -H 'Content-Type: application/json' \
+  -d '{ "storefront_access": "login_required", "guest_checkout": false }'
+```
+
+
+Switching a channel between modes takes effect immediately — the posture is resolved per request, so no cache warm-up or redeploy is needed. The Next.js storefront's [wholesale portal](../storefront/nextjs/wholesale.md) is a worked example of a `login_required` / `prices_hidden` channel driving the UI.
+
 ## Publishing Products on Channels
 
 ### Dashboard
@@ -172,3 +220,4 @@ The write contract is **full-set**: the array represents the complete desired st
 - [Order Routing](shipments.md#order-routing) — Channels can override the store's routing strategy
 - [Store SDK: Products](../sdk/store/products.md) — Channel-scoped product listing and filtering
 - [Admin SDK: Resources](../sdk/admin/resources.md) — How `adminClient.channels.addProducts` and other resource methods are structured
+- [Wholesale Portal](../storefront/nextjs/wholesale.md) — A gated channel driving the Next.js storefront's B2B surface

package/dist/developer/core-concepts/stores.md

@@ -5,7 +5,9 @@ description: Understand Spree Stores — the top-level tenant boundary that scop
 
 ## Overview
 
-The StThe Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, taxonomies — belongs to exactly one store. A store owns its [channels](channels.md) (online, POS, wholesale, …), its [markets](markets.md) (region/currency/locale), and its [product catalog](products.md).tore Attributes
+The Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, taxonomies — belongs to exactly one store. A store owns its [channels](channels.md) (online, POS, wholesale, …), its [markets](markets.md) (region/currency/locale), and its [product catalog](products.md).
+
+## Store Attributes
 
 | Attribute | Description |
 |-----------|-------------|
@@ -19,6 +21,8 @@ The StThe Store is the top-level tenant in Spree. Every resource — products, o
 | `mail_from_address` | Sender address for transactional emails |
 | `logo_url` | URL to the store's logo |
 | `facebook`, `twitter`, `instagram` | Social media links |
+| `storefront_access` | Store-wide default for anonymous [storefront access gating](channels.md#storefront-access-gating) (`public`, `prices_hidden`, `login_required`). Each channel can override it |
+| `guest_checkout` | Store-wide default for whether orders can be placed without an account. Each channel can override it |
 
 ## Fetching Store Information
 
@@ -54,6 +58,10 @@ Two different ways to split a store, often confused:
 
 A single Online Store channel can serve multiple markets (one storefront → many regions). Conversely, POS and Online channels can share the same market (same currency/locale, different selling surfaces).
 
+### Storefront access defaults
+
+The store sets the fallback for **storefront access gating** — whether anonymous visitors may browse, see prices, or must sign in first — via `storefront_access` (`public`, `prices_hidden`, `login_required`) and the companion `guest_checkout` control. Each channel inherits these unless it sets its own value, so you can gate a whole store or just one channel (e.g. a `login_required` wholesale channel on an otherwise `public` store). The full behavior of each mode and how the Store API enforces it lives in [Channels → Storefront Access Gating](channels.md#storefront-access-gating).
+
 ## Store Resources
 
 Each store owns its own resources. Products, orders, channels, markets, and taxonomies in one store are independent from another.
@@ -64,7 +72,7 @@ Each store owns its own resources. Products, orders, channels, markets, and taxo
 | [**Markets**](markets.md) | A store has many markets, each defining a geographic region with its own currency and locale |
 | [**Orders**](orders.md) | An order belongs to one store and one channel |
 | [**Products**](products.md) | A product belongs to one store. Its visibility across channels is controlled by [publications](channels.md#publishing-products-on-channels). |
-| [**Taxonomies**](products.md#categories) | A taxonomy belongs to one store |
+| [**Categories**](products.md#categories) | A category belongs to one store |
 | [**Payment Methods**](payments.md) | A payment method belongs to one store |
 | [**Shipping Methods**](shipments.md) | A shipping method belongs to one store |
 | [**Promotions**](promotions.md) | A promotion belongs to one store |
@@ -82,4 +90,5 @@ If you need one Spree backend to serve **multiple distinct merchant brands** —
 - [Markets](markets.md) — Multi-region commerce within a store
 - [Products](products.md) — Product catalog
 - [Orders](orders.md) — Order management and checkout
+- [Wholesale Portal](../storefront/nextjs/wholesale.md) — A gated B2B storefront surface built on channel access gating
 - [Admin SDK](../sdk/admin/quickstart.md) — TypeScript client for the Admin API used to read and update store configuration

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

@@ -38,20 +38,29 @@ src/
 │       │   │   └── [slug]/          # Product details
 │       │   ├── t/[...permalink]/    # Category pages
 │       │   └── categories/          # Category overview
-│       └── (checkout)/              # Checkout layout (no header/footer)
-│           ├── checkout/[id]/       # Checkout flow
-│           └── order-placed/[id]/   # Order confirmation
+│       ├── (checkout)/              # Checkout layout (no header/footer)
+│       │   ├── checkout/[id]/       # Checkout flow
+│       │   └── order-placed/[id]/   # Order confirmation
+│       └── (wholesale)/             # Opt-in B2B portal (gated — see Wholesale guide)
+│           └── wholesale/
+│               ├── page.tsx         # Trade catalog
+│               ├── products/[slug]/ # Wholesale PDP
+│               ├── cart/            # Wholesale cart
+│               ├── quick-order/     # SKU quick-order form
+│               ├── apply/           # Trade-account application
+│               └── _components/     # Gate, header, sign-in wall, pending, guest browse
 ├── components/
 │   ├── cart/                        # CartDrawer
 │   ├── checkout/                    # AddressStep, DeliveryStep, PaymentStep, etc.
 │   ├── layout/                      # Header, Footer, CountrySwitcher
 │   ├── navigation/                  # Breadcrumbs
-│   ├── products/                    # ProductCard, ProductGrid, Filters, MediaGallery, VariantPicker
+│   ├── products/                    # ProductCard, ProductGrid, Filters, MediaGallery, HiddenPricePrompt
 │   └── search/                      # SearchBar
 ├── contexts/
 │   ├── AuthContext.tsx              # Auth state
 │   ├── CartContext.tsx              # Client-side cart state sync
 │   ├── CheckoutContext.tsx          # Checkout flow state
+│   ├── HiddenPricingContext.tsx     # Prices-hidden signal for wholesale guests
 │   └── StoreContext.tsx             # Store/locale/currency state
 ├── hooks/
 │   ├── useCarouselProducts.ts      # Product carousel data
@@ -72,7 +81,11 @@ src/
     │   ├── payment.ts               # Payment processing
     │   ├── products.ts              # Product queries
     │   ├── categories.ts            # Categories
-    │   └── utils.ts                 # Shared helpers (actionResult, withFallback)
+    │   ├── wholesale.ts             # Wholesale channel + catalog + quick-order
+    │   ├── utils.ts                 # Shared helpers (actionResult, withFallback)
+    │   └── …                        # One file per domain — see src/lib/data/
+    ├── spree/                       # Spree integration (client, cookies, auth refresh, middleware, surface)
+    ├── wholesale.ts                 # Approval check + volume-pricing helpers
     └── utils/                       # Client utilities
         ├── address.ts               # Address formatting
         ├── cookies.ts               # Cookie helpers
@@ -81,6 +94,8 @@ src/
         └── product-query.ts         # Product filter query builder
 ```
 
+The `(wholesale)` route group is an opt-in B2B portal, off unless a wholesale channel is configured. Its gating, surfaces, and pricing modes are covered in the [Wholesale Portal](wholesale.md) guide.
+
 ## Authentication Flow
 
 1. User submits login form
@@ -107,17 +122,9 @@ export async function getCustomer() {
 }
 ```
 
-## Multi-Region Support
-
-The storefront supports multiple countries and currencies via URL segments:
-
-```
-/us/en/products          # US store, English
-/de/de/products          # German store, German
-/uk/en/products          # UK store, English
-```
+## Multi-Region
 
-A middleware (`src/proxy.ts`) uses `createSpreeMiddleware` from `src/lib/spree` to detect the visitor's country and locale, then redirects to the correct URL prefix. The `CountrySwitcher` component lets users change regions manually.
+The storefront serves multiple countries, currencies, and languages from one deployment via `/{country}/{locale}` URL segments and an edge middleware that detects and persists the visitor's region. See the [Multi-Region](multi-region.md) guide.
 
 ## Server Actions
 

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

@@ -1,35 +1,19 @@
 ---
 title: Customization
-description: Fork, customize, and extend the Spree Next.js Storefront
+description: Customize and extend the Spree Next.js Storefront
 ---
 
-## Forking the Starter
+The storefront is yours to modify — the code ships in your project so you can restyle it, swap components, and change the data layer directly. Scaffold a project with [`create-spree-app`](quickstart.md#installation), then edit the storefront under `apps/storefront/`.
 
-The recommended approach is to fork the repository so you can customize freely while pulling upstream updates.
+## Tracking Upstream Updates
 
-### 1. Fork on GitHub
-
-Go to [github.com/spree/storefront](https://github.com/spree/storefront) and click **Fork**.
-
-### 2. Clone Your Fork
-
-```bash
-git clone https://github.com/YOUR_USERNAME/storefront.git
-cd storefront
-npm install
-```
-
-### 3. Add Upstream Remote
+The storefront evolves upstream. To keep pulling improvements while you customize, own the code in your own Git repository (a fork of [spree/storefront](https://github.com/spree/storefront), or your own repo with the storefront as an upstream remote):
 
 ```bash
+# Point an "upstream" remote at the official storefront
 git remote add upstream https://github.com/spree/storefront.git
-```
-
-### 4. Pull Upstream Updates
 
-When the official starter gets updates, pull them into your fork:
-
-```bash
+# Pull in the latest changes
 git fetch upstream
 git merge upstream/main
 ```
@@ -138,66 +122,8 @@ export default async function YourNewPage() {
 
 ## Transactional Emails
 
-Customer-facing emails are rendered in the storefront using [react-email](https://react.email) and sent via [Resend](https://resend.com). The Spree backend delivers order/shipment/password events to the storefront via [webhooks](../../core-concepts/webhooks.md).
-
-### Templates
-
-Email templates are React components in `src/lib/emails/`:
-
-| File | Event | Description |
-|------|-------|-------------|
-| `order-confirmation.tsx` | `order.completed` | Items, totals, addresses, delivery method |
-| `order-canceled.tsx` | `order.canceled` | Cancellation notice with items |
-| `shipment-shipped.tsx` | `order.shipped` | Tracking number and link |
-| `password-reset.tsx` | `customer.password_reset_requested` | Reset button and fallback link |
-| `newsletter-confirmation.tsx` | `newsletter_subscriber.subscription_requested` | Double opt-in confirmation link |
-
-Customize templates by editing these files directly. They use `@react-email/components` for email-safe layout primitives.
-
-### Previewing
-
-```bash
-npm run email:dev
-```
-
-Opens the react-email dev server with mock data for all templates at `http://localhost:3000`.
-
-### Webhook Handler
-
-The webhook route (`src/app/api/webhooks/spree/route.ts`) uses `createWebhookHandler` from `src/lib/spree/webhooks`:
-
-```typescript
-import { createWebhookHandler } from '@/lib/spree/webhooks'
-
-export const POST = createWebhookHandler({
-  secret: process.env.SPREE_WEBHOOK_SECRET!,
-  handlers: {
-    'order.completed': handleOrderCompleted,
-    'order.canceled': handleOrderCanceled,
-    'order.shipped': handleOrderShipped,
-    'customer.password_reset_requested': handlePasswordReset,
-    'newsletter_subscriber.subscription_requested': handleNewsletterConfirmation,
-  },
-})
-```
-
-To add a new email type:
-
-1. Create a template in `src/lib/emails/`
-2. Add a handler function in `src/lib/webhooks/handlers.ts`
-3. Register the event in `route.ts`
-4. Subscribe to the event in Spree Admin → Webhooks
-
-### Local Development
-
-In dev, emails are written to `.next/emails/` as HTML files — no Resend key needed. Use [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/) to receive webhooks locally:
-
-```bash
-cloudflared tunnel --url http://localhost:3001
-```
-
-For full setup details, see [Sending out Emails](../../deployment/emails.md).
+The storefront can render and send its own order, shipment, and account emails with react-email and Resend, driven by Spree webhooks. See the dedicated [Transactional Emails](emails.md) guide.
 
 ## Building a Custom Storefront
 
-If you prefer to build from scratch instead of forking the starter, you can use the `@spree/sdk` package directly in any Next.js application. The storefront's `src/lib/spree/` directory contains reusable helpers for cookie-based auth, locale resolution, middleware, and webhook verification that you can copy into your own project.
+If you prefer to build from scratch instead of using the starter, you can use the `@spree/sdk` package directly in any Next.js application. The storefront's `src/lib/spree/` directory contains reusable helpers for cookie-based auth, locale resolution, middleware, and webhook verification that you can copy into your own project.

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

@@ -5,26 +5,7 @@ description: Deploy the Spree Next.js Storefront to Vercel, Docker, or any Node.
 
 ## Environment Variables
 
-Set these variables in your hosting platform's dashboard or `.env` file.
-
-### Required
-
-| Variable | Description |
-|----------|-------------|
-| `SPREE_API_URL` | Your Spree API endpoint (e.g., `https://api.mystore.com`) |
-| `SPREE_PUBLISHABLE_KEY` | Publishable API key from your Spree admin |
-
-> **NOTE:** These are server-side only variables — no `NEXT_PUBLIC_` prefix needed since all API calls happen in Server Actions.
-
-### Optional
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `GTM_ID` | Google Tag Manager container ID | _(disabled)_ |
-| `SENTRY_DSN` | Sentry DSN for error tracking | _(disabled)_ |
-| `SENTRY_ORG` | Sentry organization slug | _(none)_ |
-| `SENTRY_PROJECT` | Sentry project slug | _(none)_ |
-| `SENTRY_AUTH_TOKEN` | Sentry auth token (for source maps in CI) | _(none)_ |
+At minimum, set `SPREE_API_URL` and `SPREE_PUBLISHABLE_KEY` in your hosting platform's dashboard or `.env` file. See [Environment Variables](environment-variables.md) for the full reference — analytics, error tracking, wholesale, emails, and SEO.
 
 ## Production Build
 
@@ -43,7 +24,13 @@ Vercel is the recommended deployment platform for Next.js applications.
 
 1. Push your code to GitHub
 2. Go to [vercel.com/new](https://vercel.com/new) and import your repository
-3. Add environment variables (`SPREE_API_URL`, `SPREE_PUBLISHABLE_KEY`)
+3. Add environment variables:
+   - `SPREE_API_URL` and `SPREE_PUBLISHABLE_KEY` (required)
+   - `SPREE_WEBHOOK_SECRET`, `RESEND_API_KEY`, `EMAIL_FROM` — for [transactional emails](emails.md)
+   - `GTM_ID` — optional, Google Tag Manager
+   - `SENTRY_DSN`, `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_AUTH_TOKEN` — optional, error tracking with readable stack traces
+
+   See the [Environment Variables reference](environment-variables.md) for the full list.
 4. Click **Deploy**
 
 Vercel automatically detects the Next.js framework and configures the build settings.
@@ -61,56 +48,50 @@ Every pull request gets a unique preview URL, making it easy to test storefront
 
 ## Docker
 
-Create a `Dockerfile` in your project root:
+A multi-stage `Dockerfile` ships at the repo root. It uses Next.js standalone output to produce a small (~240 MB) image on `node:22-alpine`, runs as a non-root user, and exposes port `3001`.
 
-```dockerfile
-FROM node:20-alpine AS base
+> **NOTE:** `SPREE_API_URL` and `SPREE_PUBLISHABLE_KEY` are required at **build time** — the storefront prerenders pages against the Spree API. Point them at a Spree instance reachable from wherever you run `docker build` (hosted Spree, a tunnel, or `host.docker.internal` for a local backend on Docker Desktop).
 
-FROM base AS deps
-WORKDIR /app
-COPY package.json package-lock.json ./
-RUN npm ci --production=false
-
-FROM base AS builder
-WORKDIR /app
-COPY --from=deps /app/node_modules ./node_modules
-COPY . .
-RUN npm run build
+Build and run:
 
-FROM base AS runner
-WORKDIR /app
-ENV NODE_ENV=production
+```bash
+docker build \
+  --build-arg SPREE_API_URL=https://your-spree.example.com \
+  --build-arg SPREE_PUBLISHABLE_KEY=your_publishable_key \
+  -t spree-storefront .
 
-RUN addgroup --system --gid 1001 nodejs
-RUN adduser --system --uid 1001 nextjs
+docker run -p 3001:3001 --env-file .env.local spree-storefront
+```
 
-COPY --from=builder /app/public ./public
-COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
-COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+### Sentry source maps at build time
 
-USER nextjs
-EXPOSE 3000
-ENV PORT=3000
-ENV HOSTNAME="0.0.0.0"
+`SENTRY_AUTH_TOKEN` is passed via a BuildKit secret so it never lands in image layers or the build cache. The other Sentry vars are regular build args:
 
-CMD ["node", "server.js"]
+```bash
+SENTRY_AUTH_TOKEN=... docker build \
+  --build-arg SPREE_API_URL=... \
+  --build-arg SPREE_PUBLISHABLE_KEY=... \
+  --build-arg SENTRY_DSN=... \
+  --build-arg SENTRY_ORG=... \
+  --build-arg SENTRY_PROJECT=... \
+  --secret id=sentry_auth_token,env=SENTRY_AUTH_TOKEN \
+  -t spree-storefront .
 ```
 
-> **NOTE:** Enable standalone output in your `next.config.ts` for Docker deployments:
-> 
->   ```typescript
-  const nextConfig = {
-    output: 'standalone',
-  }
-  ```
+### Building against a local Spree backend
 
-Build and run:
+On Docker Desktop (macOS/Windows), reach the host's Spree via `host.docker.internal`:
 
 ```bash
-docker build -t spree-storefront .
-docker run -p 3000:3000 \
-  -e SPREE_API_URL=https://api.mystore.com \
-  -e SPREE_PUBLISHABLE_KEY=your_key \
+docker build \
+  --add-host=host.docker.internal:host-gateway \
+  --build-arg SPREE_API_URL=http://host.docker.internal:3000 \
+  --build-arg SPREE_PUBLISHABLE_KEY=your_publishable_key \
+  -t spree-storefront .
+
+docker run -p 3001:3001 \
+  --add-host=host.docker.internal:host-gateway \
+  --env-file .env.local \
   spree-storefront
 ```
 
@@ -131,7 +112,7 @@ npm run build
 npm start
 ```
 
-The server listens on port `3000` by default. Set the `PORT` environment variable to change it.
+The server listens on port `3001`. Set the `PORT` environment variable to change it.
 
 ## CI/CD
 

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

@@ -0,0 +1,86 @@
+---
+title: Transactional Emails
+description: Render and send order, shipment, and account emails from the Spree Next.js Storefront with react-email, Resend, and Spree webhooks
+---
+
+The storefront can own its customer-facing transactional emails instead of the Spree backend. Emails are rendered with [react-email](https://react.email) and sent via [Resend](https://resend.com); the Spree backend delivers order, shipment, and account events to the storefront over [webhooks](../../core-concepts/webhooks.md).
+
+```
+Spree Backend → Webhook POST → /api/webhooks/spree → render email → send via Resend
+(signed HMAC)                  (signature verified)  (react-email)  (or write to disk in dev)
+```
+
+## Templates
+
+Email templates are React components in `src/lib/emails/`:
+
+| File | Event | Description |
+|------|-------|-------------|
+| `order-confirmation.tsx` | `order.completed` | Items, totals, addresses, delivery method |
+| `order-canceled.tsx` | `order.canceled` | Cancellation notice with items |
+| `shipment-shipped.tsx` | `order.shipped` | Tracking number and link |
+| `password-reset.tsx` | `customer.password_reset_requested` | Reset button and fallback link |
+
+Customize a template by editing its file directly — they use `@react-email/components` for email-safe layout primitives.
+
+## Previewing
+
+Run the storefront in development and open [http://localhost:3001/dev/emails](http://localhost:3001/dev/emails):
+
+```bash
+npm run dev
+```
+
+Each template renders with sample data via `@react-email/render`. The route is gated to non-production environments.
+
+## Configuration
+
+Add these to `.env.local`:
+
+```env
+SPREE_WEBHOOK_SECRET=your_webhook_endpoint_secret_key
+RESEND_API_KEY=re_your_resend_api_key            # production only
+EMAIL_FROM=Your Store <orders@your-domain.com>   # production only
+```
+
+In development no `RESEND_API_KEY` is needed — emails are written to `.next/emails/` as HTML files with a `file://` link logged to the console.
+
+## Webhook Handler
+
+The webhook route (`src/app/api/webhooks/spree/route.ts`) wires events to handlers with `createWebhookHandler` from `src/lib/spree/webhooks`. Signature verification and event routing are handled for you:
+
+```typescript
+import { createWebhookHandler } from '@/lib/spree/webhooks'
+
+const handler = createWebhookHandler({
+  secret: process.env.SPREE_WEBHOOK_SECRET!,
+  handlers: {
+    'order.completed': handleOrderCompleted,
+    'order.canceled': handleOrderCanceled,
+    'order.shipped': handleOrderShipped,
+    'customer.password_reset_requested': handlePasswordReset,
+  },
+})
+```
+
+To add a new email type:
+
+1. Create a template in `src/lib/emails/`.
+2. Add a handler function in `src/lib/webhooks/handlers.ts`.
+3. Register the event in `route.ts`.
+4. Subscribe to the event in **Spree Admin → Settings → Developers → Webhooks**.
+
+## Setup
+
+1. **Create a webhook endpoint** in Spree Admin → Settings → Developers → Webhooks. Subscribe to `order.completed`, `order.canceled`, `order.shipped`, and `customer.password_reset_requested`, and copy the secret key into `SPREE_WEBHOOK_SECRET`.
+
+2. **Receive webhooks locally.** Expose the storefront with a public URL so Spree can reach it — the simplest option is a [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/):
+
+   ```bash
+   brew install cloudflared
+   cloudflared tunnel --url http://localhost:3001
+   ```
+
+   Use the tunnel URL as the webhook endpoint URL in Spree Admin.
+
+For the backend perspective on delivering these events, see [Sending out Emails](../../deployment/emails.md).

package/dist/developer/storefront/nextjs/environment-variables.md

@@ -0,0 +1,88 @@
+---
+title: Environment Variables
+description: Every environment variable the Spree Next.js Storefront reads, with defaults and when to set it
+---
+
+Configuration lives in `.env.local` (copy `.env.example` to start). Variables **without** a `NEXT_PUBLIC_` prefix are server-side only and never reach the browser; `NEXT_PUBLIC_` variables are inlined into the client bundle at build time, so only put non-secret values there.
+
+## Required
+
+| Variable | Description |
+|----------|-------------|
+| `SPREE_API_URL` | Your Spree API endpoint (e.g. `http://localhost:3000` in dev, `https://api.mystore.com` in production) |
+| `SPREE_PUBLISHABLE_KEY` | Publishable API key from your Spree admin |
+
+> **NOTE:** In a Docker build these two are also required at **build time** — the storefront prerenders pages against the Spree API. See [Deployment](deployment.md).
+
+## Store defaults
+
+Used by the middleware for initial redirects before API data loads, and as build-time fallbacks for sitemap/SEO generation.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NEXT_PUBLIC_DEFAULT_COUNTRY` | Default country ISO code — should match your store's `default_country_iso` | `us` |
+| `NEXT_PUBLIC_DEFAULT_LOCALE` | Default locale code — should match your store's `default_locale` | `en` |
+| `NEXT_PUBLIC_SITE_URL` | Public site URL, used for sitemap and `robots.txt` generation (e.g. `https://mystore.com`) | _(required for sitemap)_ |
+| `NEXT_PUBLIC_STORE_NAME` | Store name used in metadata fallbacks | `Spree Store` |
+| `NEXT_PUBLIC_STORE_DESCRIPTION` | Store description used in metadata fallbacks | _(sample text)_ |
+
+## SEO & social
+
+Optional overrides for site metadata and the Organization JSON-LD. When unset, values fall back to store settings from the Spree API.
+
+| Variable | Description |
+|----------|-------------|
+| `STORE_SEO_TITLE` | Default `<title>` |
+| `STORE_META_DESCRIPTION` | Default meta description |
+| `STORE_META_KEYWORDS` | Default meta keywords |
+| `STORE_TWITTER` | Twitter/X handle or URL |
+| `STORE_FACEBOOK` | Facebook page URL |
+| `STORE_INSTAGRAM` | Instagram URL |
+| `STORE_LOGO_URL` | Logo URL for Organization JSON-LD |
+| `STORE_SUPPORT_EMAIL` | Customer support email |
+
+## Wholesale B2B portal
+
+The [wholesale portal](wholesale.md) is an opt-in addon, off by default.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SPREE_WHOLESALE_CHANNEL` | Enable switch — the code of a gated Spree channel to bind the `/wholesale` surface to. Unset means DTC-only: every wholesale entry point is hidden and the routes 404 | _(disabled)_ |
+| `SPREE_WHOLESALE_PUBLISHABLE_KEY` | Channel-scoped publishable key for the wholesale surface. Optional — the channel header selects the channel, so this falls back to `SPREE_PUBLISHABLE_KEY` | _(falls back to `SPREE_PUBLISHABLE_KEY`)_ |
+
+## Transactional emails
+
+See the [Transactional Emails](emails.md) guide for the full setup.
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SPREE_WEBHOOK_SECRET` | Webhook endpoint secret key that signs incoming Spree webhooks | _(disabled)_ |
+| `RESEND_API_KEY` | [Resend](https://resend.com) API key for sending emails in production | _(dev: writes to disk)_ |
+| `EMAIL_FROM` | "From" address for transactional emails (e.g. `Store <orders@mystore.com>`) | `orders@example.com` |
+
+## Payments
+
+Publishable keys for client-side payment SDKs, read when the matching gateway is enabled. Set the key for whichever provider(s) you use.
+
+| Variable | Description |
+|----------|-------------|
+| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Stripe publishable key (`pk_…`) |
+
+## Analytics
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GTM_ID` | Google Tag Manager container ID (e.g. `GTM-XXXXXXX`). Leave empty to disable | _(disabled)_ |
+
+## Error tracking (Sentry)
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SENTRY_DSN` | Sentry DSN — set to enable error tracking (e.g. `https://key@o0.ingest.sentry.io/0`) | _(disabled)_ |
+| `SENTRY_ORG` | Sentry organization slug (for source map uploads) | _(none)_ |
+| `SENTRY_PROJECT` | Sentry project slug (for source map uploads) | _(none)_ |
+| `SENTRY_AUTH_TOKEN` | Sentry auth token (for source map uploads in CI) | _(none)_ |
+| `SENTRY_SEND_DEFAULT_PII` | Send PII (IP addresses, cookies, user data) to Sentry server-side | `false` |
+| `NEXT_PUBLIC_SENTRY_SEND_DEFAULT_PII` | Send PII to Sentry client-side | `false` |
+
+> **WARNING:** PII collection is disabled by default. Only set the `SENTRY_SEND_DEFAULT_PII` variables to `true` if you have appropriate user consent or a privacy policy covering this data.