Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Retarget the project layout & dashboard plan to 5.6
Damian Legawieca5a04517a035
diff --git a/CLAUDE.md b/CLAUDE.mdindex 5ccc5ab7f1..04f5e69788 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -46,6 +46,7 @@ Pending design work (drafts, no implementation yet):- `5.4-centralized-translations-admin.md` — Centralized Translations admin page under Products, overview grid + bulk CSV import/export- `5.4-metafield-translations.md` — Translate MetafieldDefinition names + Metafield text values (ShortText, LongText, RichText) via Mobility translation tables- `5.5-admin-api-cli.md` — `spree api` command group in `@spree/cli` (gh-api-style generic verbs + schema introspection + layered auth, CLI-first ahead of MCP servers; core patch: `SCOPES` on `spree:cli:create_api_key`, promotions scopes)+- `5.6-project-layout-and-dashboard.md` — React Dashboard Developer Preview packaging: `create-spree-app` renames `backend/` → `api/` for new projects, dashboard scaffolds into `apps/dashboard/` from a `spree/dashboard-starter` template, new `spree add dashboard` + `spree upgrade layout` commands, dual-layout CLI support via `detectApiDir` until 6.0 GAShipped plans:- `5.4-store-api-bridges.md` — Bridge 6.0 naming into 5.4 Store API (PR #13782)diff --git a/docs/plans/5.4-spree-starter-and-create-spree-app.md b/docs/plans/5.4-spree-starter-and-create-spree-app.mdindex 8136c50c3c..334fb3691a 100644--- a/docs/plans/5.4-spree-starter-and-create-spree-app.md+++ b/docs/plans/5.4-spree-starter-and-create-spree-app.md@@ -6,7 +6,7 @@**Author:** Damian + Claude**Last updated:** 2026-03-18-> **Partially superseded by `5.5-project-layout-and-dashboard.md`:**+> **Partially superseded by `5.6-project-layout-and-dashboard.md`:**> - `backend/` directory renamed to `api/` for new projects scaffolded on 5.5+. Existing 5.4 projects keep `backend/` and can opt in via `spree upgrade layout`.> - `apps/admin/` reference for the future React admin (mentioned in this plan's Problem #5 and Design Details) is replaced by `apps/dashboard/`, matching the `@spree/dashboard` package name.diff --git a/docs/plans/5.5-project-layout-and-dashboard.md b/docs/plans/5.6-project-layout-and-dashboard.mdsimilarity index 92%rename from docs/plans/5.5-project-layout-and-dashboard.mdrename to docs/plans/5.6-project-layout-and-dashboard.mdindex 6c64e919ad..b6b809af0d 100644--- a/docs/plans/5.5-project-layout-and-dashboard.md+++ b/docs/plans/5.6-project-layout-and-dashboard.md@@ -1,18 +1,18 @@-# 5.5 Project Layout & Dashboard Scaffolding+# 5.6 Project Layout & Dashboard Scaffolding**Status:** Draft-**Target:** Spree 5.5 (Dashboard Developer Preview)+**Target:** Spree 5.6 (Dashboard Developer Preview)**Depends on:** `5.4-spree-starter-and-create-spree-app.md` (shipped), `6.0-admin-spa.md`**Author:** Damian + Claude-**Last updated:** 2026-05-31+**Last updated:** 2026-07-06## Summary-Ship the React dashboard as part of `create-spree-app` in 5.5 (Developer Preview) and align the generated project layout with the future API-only Rails role. The Rails app directory is renamed `backend/` → `api/` for all **new** projects scaffolded on 5.5+ — the name change is more honest the moment a second frontend exists (the dashboard), even though Rails still serves the legacy admin until 6.0. Existing projects are unaffected: they continue to work as-is, and can opt in to the new layout via `spree upgrade layout` whenever they want. The dashboard scaffolds into `apps/dashboard/` alongside the existing `apps/storefront/`, and a new `spree add dashboard` command lets existing projects bolt it on. By 6.0 GA the rename is well-trodden and the legacy `backend/` layout becomes unsupported.+Ship the React dashboard as part of `create-spree-app` in 5.6 (Developer Preview) and align the generated project layout with the future API-only Rails role. The Rails app directory is renamed `backend/` → `api/` for all **new** projects scaffolded on 5.6+ — the name change is more honest the moment a second frontend exists (the dashboard), even though Rails still serves the legacy admin until 6.0. Existing projects are unaffected: they continue to work as-is, and can opt in to the new layout via `spree upgrade layout` whenever they want. The dashboard scaffolds into `apps/dashboard/` alongside the existing `apps/storefront/`, and a new `spree add dashboard` command lets existing projects bolt it on. By 6.0 GA the rename is well-trodden and the legacy `backend/` layout becomes unsupported.## Problem-1. **`backend/` no longer describes the role.** Even in 5.5 the Rails app is already serving two distinct frontends (storefront and dashboard) plus background workers. Generic role names ("backend") stop working as soon as two frontends consume the API — "which backend?". In 6.0 the Rails app loses its admin UI entirely and becomes a thin REST API plus workers, making the name even more misleading.+1. **`backend/` no longer describes the role.** Even in 5.6 the Rails app is already serving two distinct frontends (storefront and dashboard) plus background workers. Generic role names ("backend") stop working as soon as two frontends consume the API — "which backend?". In 6.0 the Rails app loses its admin UI entirely and becomes a thin REST API plus workers, making the name even more misleading.2. **The 5.4 plan reserved `apps/admin/` for the future dashboard.** That name collides with the legacy Rails `spree/admin` engine and with `@spree/dashboard`, the package name used everywhere else in the monorepo. We should land on one name and use it consistently.@@ -27,29 +27,29 @@ Ship the React dashboard as part of `create-spree-app` in 5.5 (Developer Preview- **`apps/` holds JS/TS deployables; `api/` stays at the root.** Don't move the Rails app under `apps/api/`. It's qualitatively different (different language, different runtime, different CLI surface via `spree console`/`spree logs`) and keeping it at the root signals "this is the core; the JS apps consume it."- **The dashboard is optional, like the storefront.** Default to including it interactively; allow `--no-dashboard` / `--dashboard` flags and a non-interactive default for CI.- **Dashboard ships from a new `spree/dashboard-starter` GitHub template repo,** following the same pattern as `spree-starter` and `storefront`. Not bundled into create-spree-app.-- **Rename ships day-one in 5.5 for *new* projects.** `npx create-spree-app` on 5.5+ produces `api/` directly. We don't ship 5.5 with the dashboard inside `backend/` only to rename in 6.0 — that'd give the Developer Preview audience a layout we know will change. Get it right once.-- **Existing projects are NOT auto-migrated in 5.5.** They keep `backend/` and continue to work. The CLI detects the layout per-command (see `detectApiDir` in Design Details). Users opt in to the rename via `spree upgrade layout` on their own schedule.-- **Dual-layout support is bounded.** 5.5 and the 5.x line support both layouts; 6.0 GA drops `backend/` detection. Users have a full minor-version cycle to run `spree upgrade layout` before it's required.-- **Two new CLI commands ship in 5.5:**+- **Rename ships day-one in 5.6 for *new* projects.** `npx create-spree-app` on 5.6+ produces `api/` directly. We don't ship 5.6 with the dashboard inside `backend/` only to rename in 6.0 — that'd give the Developer Preview audience a layout we know will change. Get it right once.+- **Existing projects are NOT auto-migrated in 5.6.** They keep `backend/` and continue to work. The CLI detects the layout per-command (see `detectApiDir` in Design Details). Users opt in to the rename via `spree upgrade layout` on their own schedule.+- **Dual-layout support is bounded.** 5.6 and the 5.x line support both layouts; 6.0 GA drops `backend/` detection. Users have a full minor-version cycle to run `spree upgrade layout` before it's required.+- **Two new CLI commands ship in 5.6:**- `spree add dashboard` — clone dashboard-starter into `apps/dashboard/`, mint API keys, write `.env.local`, install deps. Idempotent (re-running with `apps/dashboard/` present is a no-op with a warning).- `spree upgrade layout` — rename `backend/` → `api/`, rewrite compose files, README, CI, `.env`. Refuses to run with a dirty working tree. Commits as a single atomic commit.-- **`spree add dashboard` works on both layouts in 5.5.** No need to upgrade first — it detects whether the Rails dir is `backend/` or `api/` and configures accordingly. (`spree upgrade layout` is independent of `add dashboard`.)-- **5.5 release notes call out the rename for *new* projects only.** Existing-project users see no surprise — their CLI keeps working unchanged. The upgrade is presented as an optional alignment step, not a forced migration.+- **`spree add dashboard` works on both layouts in 5.6.** No need to upgrade first — it detects whether the Rails dir is `backend/` or `api/` and configures accordingly. (`spree upgrade layout` is independent of `add dashboard`.)+- **5.6 release notes call out the rename for *new* projects only.** Existing-project users see no surprise — their CLI keeps working unchanged. The upgrade is presented as an optional alignment step, not a forced migration.## Design Details-### Target generated layout (5.5, new projects)+### Target generated layout (5.6, new projects)```my-shop/-├── api/ ← Rails (API + admin engine in 5.5, workers); renamed from backend/+├── api/ ← Rails (API + admin engine in 5.6, workers); renamed from backend/│ ├── Gemfile│ ├── Dockerfile│ ├── config/│ ├── app/│ └── ...├── apps/-│ ├── dashboard/ ← new: React SPA (Vite, @spree/admin-sdk) — Developer Preview in 5.5+│ ├── dashboard/ ← new: React SPA (Vite, @spree/admin-sdk) — Developer Preview in 5.6│ │ ├── package.json│ │ ├── vite.config.ts│ │ ├── src/@@ -78,11 +78,11 @@ my-shop/| `server/` | "a server doing some stuff" | Implies generality (SSR, websockets, etc.); doesn't tell you what's served | ❌ || `api/` | "this is the API surface" | Matches Vercel/Turborepo/T3 conventions for API-only services; instantly legible | ✅ |-Even in 5.5, where Rails still serves the legacy `spree/admin` engine, the *contract* exposed to JS consumers is the REST API. By 6.0 the admin engine is gone and the directory contents perfectly match the name. Sidekiq workers (webhook delivery, event processing) are part of that API surface from any external observer's perspective. The directory name should describe the role to the outside world, not the internal process model.+Even in 5.6, where Rails still serves the legacy `spree/admin` engine, the *contract* exposed to JS consumers is the REST API. By 6.0 the admin engine is gone and the directory contents perfectly match the name. Sidekiq workers (webhook delivery, event processing) are part of that API surface from any external observer's perspective. The directory name should describe the role to the outside world, not the internal process model.### Dual-layout detection (`detectApiDir`)-In 5.5 the CLI must work against both `backend/` (5.4 projects, unmigrated) and `api/` (new 5.5+ projects, or migrated 5.4 projects). One helper centralizes the detection so individual commands don't repeat the check.+In 5.6 the CLI must work against both `backend/` (pre-5.6 projects, unmigrated) and `api/` (new 5.6+ projects, or migrated older projects). One helper centralizes the detection so individual commands don't repeat the check.```typescript// packages/cli/src/context.ts (extension)@@ -119,7 +119,7 @@ export function detectProject(cwd: string = process.cwd()): ProjectContext {**Usage pattern:** every command that references the Rails directory uses `ctx.apiDir` instead of a hardcoded string. Example: `spree eject` builds `path.join(ctx.projectDir, ctx.apiDir)` and looks for `docker-compose.dev.yml` whose `context:` already matches whatever the project was scaffolded with (compose files don't need rewriting — they were written correctly at scaffold time).**Deprecation timeline:**-- **5.5:** both layouts supported; new projects scaffold as `api/`; `spree upgrade layout` available.+- **5.6:** both layouts supported; new projects scaffold as `api/`; `spree upgrade layout` available.- **5.x:** same. No CLI warning yet — users on `backend/` see no nag.- **6.0 RC:** `spree dev` (and other commands) print a deprecation warning when `backend/` is detected, pointing to `spree upgrade layout`.- **6.0 GA:** `detectApiDir` drops the `backend/` branch. Old-layout projects must run `spree upgrade layout` before any CLI command works.@@ -249,7 +249,7 @@ async function addDashboard(ctx: ProjectContext) {rmSync(join(dashboardDir, '.git'), { recursive: true, force: true })// 3. Mint admin API key via Rails (containers must be running).- // ctx.apiDir is 'api' or 'backend' — works for both 5.4 and 5.5+ projects.+ // ctx.apiDir is 'api' or 'backend' — works for both pre-5.6 and 5.6+ projects.if (!(await isWebContainerRunning(ctx))) {log.info(`Starting ${ctx.apiDir} so we can mint an admin API key...`)await dockerCompose(['up', '-d'], ctx.projectDir)@@ -408,7 +408,7 @@ function rewriteBackendReferences(content: string): string {### CLI surface summary-| Command | Purpose | New in 5.5? |+| Command | Purpose | New in 5.6? ||---|---|---|| `spree dev` | Start services | No (uses `ctx.apiDir` internally) || `spree stop` | Stop services | No |@@ -458,11 +458,11 @@ New projects scaffold straight to `api/`. There is **no dual-layout output mode***`spree/dashboard-starter` (new repo):**- Created from scratch following the shape above.-- Pinned to `@spree/dashboard@^5.5.0-next` and `@spree/admin-sdk@^5.5.0-next` (Developer Preview dist-tag), rolling forward to `^6.0.0` at 6.0 GA.+- Pinned to `@spree/dashboard@^5.6.0-next` and `@spree/admin-sdk@^5.6.0-next` (Developer Preview dist-tag), rolling forward to `^6.0.0` at 6.0 GA.## Migration Path-All phases ship in **5.5**. The dashboard ships as Developer Preview alongside `@spree/admin-sdk@next`. Versioning rolls forward to `^6.0.0` at 6.0 GA.+All phases ship in **5.6**. The dashboard ships as Developer Preview alongside `@spree/admin-sdk@next`. Versioning rolls forward to `^6.0.0` at 6.0 GA.### Phase 1: Add dual-layout detection to CLI@@ -510,11 +510,11 @@ All phases ship in **5.5**. The dashboard ships as Developer Preview alongside `1. Update `docs/developer/getting-started/` to show new layout (use `api/` in examples).2. Update `docs/developer/customization/` references.-3. Add a release-notes section in the 5.5 release notes:+3. Add a release-notes section in the 5.6 release notes:- "Dashboard Developer Preview" (the headline)- "New project layout: `api/`" (call out for newcomers)- "Existing projects: optional upgrade via `spree upgrade layout`" (set expectations — not forced)-4. Update `5.4-spree-starter-and-create-spree-app.md` with a banner noting the 5.5 rename and pointer to this plan.+4. Update `5.4-spree-starter-and-create-spree-app.md` with a banner noting the 5.6 rename and pointer to this plan.### Phase 7: Smoke test the full flow@@ -529,13 +529,13 @@ Manual QA checklist:- [ ] `npx spree upgrade layout` refuses on a dirty tree.- [ ] `npx spree upgrade layout` is a no-op on an already-upgraded project.- [ ] `npx spree add dashboard` is idempotent (second run is a no-op).-- [ ] In 5.5 RC: confirm no deprecation warning fires on `backend/` layouts. (Warnings ship in 6.0 RC, not 5.5.)+- [ ] In 5.6 RC: confirm no deprecation warning fires on `backend/` layouts. (Warnings ship in 6.0 RC, not 5.6.)## Constraints on Current Work- **Stop using `apps/admin/` in new docs, comments, or plans.** The dashboard lives at `apps/dashboard/`. The 5.4 plan's `apps/admin/` reference is superseded by this plan.-- **Use `api/` in new user-facing documentation that targets 5.5+.** For docs that span 5.4 and 5.5 (release notes, migration guides), either say "the Rails directory" generically or call out both names explicitly. Don't hardcode `backend/` as the permanent name.-- **Every new CLI command that touches the Rails directory must use `ctx.apiDir`,** never a hardcoded `'backend'` or `'api'` string. This is non-negotiable for 5.5 because both layouts coexist.+- **Use `api/` in new user-facing documentation that targets 5.6+.** For docs that span pre-5.6 and 5.6+ (release notes, migration guides), either say "the Rails directory" generically or call out both names explicitly. Don't hardcode `backend/` as the permanent name.+- **Every new CLI command that touches the Rails directory must use `ctx.apiDir`,** never a hardcoded `'backend'` or `'api'` string. This is non-negotiable for 5.6 because both layouts coexist.- **New `create-spree-app` templates and prompts must read the dashboard flag** even if dashboard scaffolding isn't fully wired up yet — so the option exists from the moment the dashboard-starter repo ships.- **The `@spree/dashboard` package must keep its current name.** Renaming it would invalidate the entire "dashboard" naming convergence.- **Admin API key minting needs to work with both publishable+secret separation.** When `spree add dashboard` mints a key for the dashboard, it must be a **secret** key with admin scopes — not a publishable key (which is for the storefront).@@ -561,11 +561,11 @@ Manual QA checklist:5. **Does `mintAdminApiKey` need a stable name/comment so users can identify it later?** When `spree add dashboard` runs, the minted key shows up in `spree api-key list`. Suggest naming it `"dashboard (created by spree add dashboard)"` or similar so users know what it's for and don't accidentally revoke it.-6. **When exactly does `backend/` support get dropped?** The plan says "by 6.0 GA". Open: do we want a 5.6 deprecation warning step in between, or jump straight from "silent dual-support in 5.5" to "warning in 6.0 RC" to "removed in 6.0 GA"? The 5.5/6.0 cycle is short enough that one warning step at 6.0 RC is probably enough.+6. **When exactly does `backend/` support get dropped?** The plan says "by 6.0 GA". Open: do we want a 5.7 deprecation warning step in between, or jump straight from "silent dual-support in 5.6" to "warning in 6.0 RC" to "removed in 6.0 GA"? The 5.6/6.0 cycle is short enough that one warning step at 6.0 RC is probably enough.## References-- **Supersedes (partial):** `docs/plans/5.4-spree-starter-and-create-spree-app.md` — specifically the `apps/admin/` reference (now `apps/dashboard/`) and the `backend/` directory name (now `api/` in 5.5+ generated projects).+- **Supersedes (partial):** `docs/plans/5.4-spree-starter-and-create-spree-app.md` — specifically the `apps/admin/` reference (now `apps/dashboard/`) and the `backend/` directory name (now `api/` in 5.6+ generated projects).- **Depends on:** `docs/plans/6.0-admin-spa.md` — defines `@spree/dashboard`, `@spree/dashboard-core`, `@spree/dashboard-ui` packages and the `defineDashboardPlugin` API consumed by the starter.- **Related:** `docs/plans/5.5-admin-api-key-scopes.md` — scope schema for the secret key minted by `spree add dashboard`.- **Related:** `docs/plans/5.5-admin-auth-cookie-refresh.md` — auth model the dashboard uses against the API.