@spree/docs 0.1.129 → 0.1.130

package/dist/developer/contributing/developing-spree.md

@@ -36,7 +36,7 @@ pnpm install        # workspace dependencies
 pnpm server:setup   # ~5–10 min on first run; idempotent
 ```
 
-`pnpm server:setup` clones [spree-starter](https://github.com/spree/spree-starter) into `./server/`, wires it to load Spree gems from the monorepo via a Docker compose overlay, builds the dev image, starts the stack (Postgres + Redis + Meilisearch + Rails `web` + Sidekiq `worker`), and prepares the database. The full sequence lives in `scripts/server-setup.sh`.
+`pnpm server:setup` clones [spree-starter](https://github.com/spree/spree-starter) into `./server/`, wires it to load Spree gems from the monorepo via a Docker compose overlay, builds the dev image, starts the stack (Postgres + Meilisearch + a single Rails `web` container — background jobs run in-process via Solid Queue), and prepares the database. The full sequence lives in `scripts/server-setup.sh`.
 
 When it's done, the backend is up at [http://localhost:3000](http://localhost:3000) and the admin is at [http://localhost:3000/admin](http://localhost:3000/admin). Sign in with the seed admin: **`spree@example.com`** / **`spree123`** (override at seed time with `ADMIN_EMAIL` / `ADMIN_PASSWORD` env vars — see `spree/core/app/services/spree/seeds/admin_user.rb`).
 
@@ -95,7 +95,7 @@ If you prefer the fastest possible inner loop and don't mind installing Ruby, Po
 pnpm server:create   # clones spree-starter, writes server/.env with SPREE_PATH=..
 cd server
 bin/setup            # installs Ruby (via mise), Postgres/Redis/Meilisearch (via brew bundle on macOS), gems, prepares the database
-bin/dev              # starts Rails + Sidekiq + CSS watchers via Foreman
+bin/dev              # starts Rails (jobs run in-process) + CSS watchers via Foreman
 ```
 
 This path is faster per request but means more on your host. It also runs against your installed system services, not a sandboxed Docker stack.

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

@@ -187,7 +187,7 @@ Spree::Admin::RuntimeConfig.reports_line_items_limit = 100
 By default, report jobs run on the `:default` queue. To route them to a dedicated queue, configure your job processor:
 
 ```ruby
-# Sidekiq example
+# ActiveJob example
 Spree.queues.reports = :reports
 ```
 

package/dist/developer/create-spree-app/quickstart.md

@@ -16,12 +16,14 @@ The CLI walks you through an interactive setup:
 2. Optionally load **sample data** (products, categories, images)
 3. Optionally **start Docker services** immediately
 
-Once complete, your store is running at [http://localhost:3000](http://localhost:3000).
+Once complete, your store is running at [http://localhost:3000](http://localhost:3000) — setup pulls the latest Spree image, seeds the database, and configures API keys, then prints a summary with your admin credentials and keys. If you skipped starting services, the first `pnpm dev` completes setup automatically.
+
+The **React Dashboard** (Developer Preview of the next-generation admin) is available with the `--react-dashboard` flag, or later via `spree add dashboard`.
 
 ## Prerequisites
 
 - [Node.js](https://nodejs.org/) 20 or later
-- [Docker](https://docs.docker.com/get-docker/) (for running the Spree backend, PostgreSQL, Redis, and Meilisearch)
+- [Docker](https://docs.docker.com/get-docker/) (for running the Spree backend, PostgreSQL, and Meilisearch)
 
 ## CLI Flags
 
@@ -33,6 +35,7 @@ npx create-spree-app@latest my-store --no-storefront --no-sample-data --no-start
 
 | Flag | Description |
 |------|-------------|
+| `--react-dashboard` | Include the React Dashboard (Developer Preview — also available later via `spree add dashboard`) |
 | `--no-storefront` | Skip Next.js storefront setup |
 | `--no-sample-data` | Skip loading sample products and categories |
 | `--no-start` | Don't start Docker services after scaffolding |
@@ -49,35 +52,39 @@ npx create-spree-app@latest my-store --no-storefront --no-sample-data --no-start
 
 ```text
 my-store/
-├── docker-compose.yml        # Spree backend (prebuilt image) + Postgres + Redis + Meilisearch
+├── docker-compose.yml        # Spree backend (prebuilt image) + Postgres + Meilisearch
 ├── docker-compose.dev.yml    # Alternative: build from local backend/
-├── .env                      # SECRET_KEY_BASE, SPREE_PORT, SPREE_VERSION_TAG
+├── render.yaml               # Render Blueprint — one Docker service built from this repo
+├── .env                      # SECRET_KEY_BASE, SPREE_PORT, SPREE_VERSION_TAG, SPREE_SAMPLE_DATA
+├── .dockerignore             # Keeps the production build context to sources
 ├── .gitignore
 ├── package.json              # Convenience scripts
 ├── README.md
-├── backend/                  # Full Rails app (from spree/spree-starter)
+├── backend/                  # Full Rails app — the Spree API (from spree/spree-starter)
 │   ├── Gemfile
-│   ├── Dockerfile
+│   ├── Dockerfile            # Also builds the production image (API + dashboard)
 │   ├── config/
 │   ├── app/
 │   └── ...
 └── apps/
-    └── storefront/           # Next.js storefront (unless --no-storefront)
-        ├── .env.local        # API URL + API key
+    ├── storefront/           # Next.js storefront (unless --no-storefront)
+    │   ├── .env.local        # API URL + API key
+    │   └── ...
+    └── dashboard/            # React Dashboard (with --react-dashboard)
+        ├── .env.local        # Dev proxy target — no credentials
         └── ...
 ```
 
 ### What's in docker-compose.yml
 
-- **Spree** — `web` (Rails) + `worker` (Sidekiq) running the `ghcr.io/spree/spree:latest` image on the configured port (default `3000`)
+- **Spree** — one `web` container running the `ghcr.io/spree/spree:latest` image on the configured port (default `3000`); background jobs run in-process via Solid Queue (stored in Postgres — job dashboard at `/jobs`)
 - **PostgreSQL 18** — database with persistent volume
-- **Redis 7** — caching, background jobs, and Action Cable
 - **Meilisearch** — search engine
-- Health checks on postgres, redis, meilisearch, and web
+- Health checks on postgres, meilisearch, and web
 
-## Customizing the Backend
+## Customizing the Spree API
 
-The `backend/` directory contains a full Rails application with Spree installed (cloned from [spree-starter](https://github.com/spree/spree-starter)). By default, the project uses a prebuilt Docker image. To switch to building from your local backend:
+The `backend/` directory is the Spree API — a full Rails application with Spree installed (cloned from [spree-starter](https://github.com/spree/spree-starter)) serving the Store and Admin APIs your storefront and dashboard talk to, plus background jobs and transactional emails. By default, the project runs it from a prebuilt Docker image. To switch to building from your local copy:
 
 ```bash
 npx spree eject
@@ -99,10 +106,12 @@ The project includes [@spree/cli](../cli/quickstart.md) for managing your Spree
 
 | Command | Description |
 |---------|-------------|
-| `spree dev` | Run the backend in the foreground — streams logs, Ctrl+C stops it |
+| `spree dev` | Run the app in the foreground — streams logs, Ctrl+C stops it. First run completes setup automatically; co-runs the React Dashboard dev server when `apps/dashboard` exists |
 | `spree stop` | Stop backend services |
 | `spree update` | Pull latest Spree image and restart (runs migrations automatically) |
 | `spree eject` | Switch from prebuilt image to building from `backend/` |
+| `spree add dashboard` | Add the React Dashboard to an existing project |
+| `spree build --production` | Build the production image — the Spree API plus your dashboard, in one |
 | `spree logs` | View backend logs |
 | `spree logs worker` | View background jobs logs |
 | `spree console` | Rails console |
@@ -118,6 +127,8 @@ Open [http://localhost:3000/admin](http://localhost:3000/admin) and log in with:
 | **Email** | `spree@example.com` |
 | **Password** | `spree123` |
 
+With `--react-dashboard`, the React Dashboard's dev server is the admin instead: `spree dev` starts it alongside the API at [http://localhost:5173](http://localhost:5173) — same credentials, live-reloading from `apps/dashboard/` (the classic admin remains at `/admin`). See the [React Dashboard docs](../dashboard/overview.md).
+
 ### Store API
 
 The REST API is available at [http://localhost:3000/api/v3/store](http://localhost:3000/api/v3/store). See the [API Reference](/api-reference) for details.
@@ -149,6 +160,15 @@ To pin a specific version, edit `SPREE_VERSION_TAG` in `.env`:
 SPREE_VERSION_TAG=5.4
 ```
 
+## Deployment
+
+The project deploys as **one image**: `backend/Dockerfile` builds the Spree API together with your React Dashboard (when `apps/dashboard` exists), served same-origin at `/dashboard` — no CORS, no cookie configuration, no second service.
+
+- **Render** — the `render.yaml` at the project root is a ready Blueprint: one Docker service built straight from your repo, migrations run on boot.
+- **Anywhere else** — `spree build --production` builds the same image locally; push it to a registry and run it on any Docker host.
+
+See the [Deployment Guide](../deployment.md) and the [dashboard deployment docs](../dashboard/deployment.md).
+
 ## Next Steps
 
 

package/dist/developer/dashboard/deployment.md

@@ -22,16 +22,13 @@ The official image contains the *stock* dashboard. Once you've customized yours
 spree build --production            # optionally --tag registry/repo:tag
 ```
 
-The command detects `apps/dashboard/`, selects the Dockerfile's `custom` dashboard stage (`--build-arg DASHBOARD_SOURCE=custom`), and passes your app as a named build context — the Node toolchain lives only in that throw-away stage, and the final image is Rails plus your built `dist/` served at `/dashboard`. Without the CLI, the equivalent is:
+The Dockerfile normalizes its own build context: built from the project root it detects the layout (`backend/` = the Rails app, `apps/dashboard/` = your dashboard) and builds *your* dashboard into the image — no flags, no named contexts. Without the CLI, the equivalent is:
 
 ```bash
-docker build backend/ -f backend/Dockerfile \
-  --build-arg DASHBOARD_SOURCE=custom \
-  --build-context dashboard-src=./apps/dashboard \
-  -t my-shop-spree:latest
+docker build . -f backend/Dockerfile -t my-shop-spree:latest
 ```
 
-Inside the stage the build runs with `VITE_BASE_PATH=/dashboard/` (asset URLs resolve under the mount) and `VITE_SPREE_API_URL` unset (API calls stay origin-relative). Projects **without** `apps/dashboard/` build exactly what plain `docker build backend/` produces — and if your `backend/Dockerfile` predates dashboard support, the command warns instead of silently shipping the stock dashboard over your customized one.
+Inside the dashboard stage the build runs with `VITE_BASE_PATH=/dashboard/` (asset URLs resolve under the mount) and `VITE_SPREE_API_URL` unset (API calls stay origin-relative); the Node toolchain lives only in that throw-away stage. Projects **without** `apps/dashboard/` get the stock dashboard baked instead — and if your `backend/Dockerfile` predates this layout support, the command warns instead of silently shipping the stock dashboard over your customized one (update it from the spree-starter template).
 
 ## Static host / CDN — the alternative
 
@@ -52,16 +49,15 @@ A middle ground also works: serve `dist/` and proxy `/api/*` + `/rails/*` to Rai
 
 ## Render
 
-If your project deploys to Render via the Blueprint that `create-spree-app` places at the project root, `spree add dashboard` wires the single-node topology automatically: it extends the backend service's `buildCommand` to also build `apps/dashboard` (Render's Ruby runtime includes Node, and the full repo is available during the build) and adds one env var so the server serves the result:
+The Blueprint that `create-spree-app` places at the project root deploys the backend as a **Docker service** built from your repo — the same Dockerfile as everywhere else, with the repo root as context:
 
 ```yaml
-buildCommand: bundle install && … && (cd ../apps/dashboard && corepack enable pnpm && pnpm install && VITE_BASE_PATH=/dashboard/ pnpm build)
-envVars:
-  - key: SPREE_DASHBOARD_DIST_PATH
-    value: ../apps/dashboard/dist
+runtime: docker
+dockerfilePath: ./backend/Dockerfile
+dockerContext: .
 ```
 
-That's the whole setup — one service, one origin, **your customized dashboard** (it builds from your `apps/dashboard`, not the stock bundle) at `https://your-service.onrender.com/dashboard`. No `VITE_SPREE_API_URL`, no Allowed Origins entry, no extra service. Redeploys rebuild on every push.
+That's the whole setup — one service, one origin, **your customized dashboard** (it builds from your `apps/dashboard`, not the stock bundle) at `https://your-service.onrender.com/dashboard`. No `VITE_SPREE_API_URL`, no Allowed Origins entry, no extra service, no build commands to maintain — migrations run from the image entrypoint on boot. Redeploys rebuild on every push, and what Render builds is byte-for-byte what `spree build --production` builds locally.
 
 If you prefer the dashboard on Render's CDN instead, add a static-site service by hand using the cross-origin recipe above.