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
Record spike result and resolved decisions in the typed-routes plan
Damian Legawiec2ecd1f75beed
diff --git a/CLAUDE.md b/CLAUDE.mdindex a90b083a89..e250bb1c7d 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -40,7 +40,7 @@ Multi-version plans (some phases shipped, some pending):- `6.0-channels-catalogs-b2b.md` — Channel + ProductPublication (replaces StoreProduct) + single-owner Product (`belongs_to :store`) + Publishing card (legacy admin + SPA) + `Channel#default` boolean shipped in 5.5. Channel-level gated storefront access (`storefront_access` enum + channel-owned `guest_checkout`, both with store fallback, enforced in the v3 Store API) targeted for 5.6. Catalog, Company/CompanyLocation/CompanyContact for B2B pending in 6.0. Multi-store catalogs (historic `Product has_many :stores`) move to the `spree_multi_store` extension.- `5.6-6.0-single-store-promotions-payment-methods.md` — Migrate `Spree::Promotion` + `Spree::PaymentMethod` from multi-store (`has_many :stores` via `spree_promotions_stores` / `spree_payment_methods_stores` join tables) to single-owner `belongs_to :store`, mirroring the 5.5 single-owner Product migration. 5.6 (implemented): `store_id` FK + required-store presence via `Spree::SingleStoreResource`, backfill rake task (loud per-record deprecation on shared records), shared `LegacyMultiStoreSupport` deprecation bridge, deletes the `ResourceController` `store_ids=` seam, deprecates `StoreScopedResource`; multi-store sharing moves to the `spree_multi_store` extension (join tables left intact). 6.0 cleanup: enforce `null: false`, drop join tables + bridges. Paired with `6.0-channels-catalogs-b2b.md`.- `5.6-project-layout-and-dashboard.md` — React Dashboard Developer Preview packaging + `backend/` → `api/` project layout. Implemented: `<Dashboard />` shell export from `@spree/dashboard` (source-only, relative imports only), monorepo-canonical `packages/dashboard-starter` thin host (synced to the `spree/dashboard-starter` template repo on release), `spree add dashboard` (env carries only `VITE_SPREE_API_URL` — never secret keys). Pending: layout rename + `detectApiDir` dual-layout CLI, create-spree-app dashboard phase, `spree upgrade layout`, template sync job.-- `5.6-dashboard-typed-plugin-routes.md` — Plugin file routes compiled into the host's TanStack route tree: `spree.dashboard.routes` marker + virtual-route-config composition in `@spree/dashboard/vite`, `createDashboardRouter` + `<Dashboard router>` ownership inversion, typed cast-free links. Runtime route registry stays for dynamic/in-app cases (catch-all is lowest priority). Implemented; published-tarball spike pending.+- `5.6-dashboard-typed-plugin-routes.md` — Plugin file routes compiled into the host's TanStack route tree: `spree.dashboard.routes` marker + virtual-route-config composition in `@spree/dashboard/vite`, `createDashboardRouter` + `<Dashboard router>` ownership inversion, typed cast-free links, cross-package collision pre-flight with package-named errors. Runtime route registry stays for dynamic/in-app cases (catch-all is lowest priority). Implemented; published-tarball spike passed.Pending design work (drafts, no implementation yet):- `5.6-admin-spa-csv-import.md` — Universal dashboard CSV import over the existing `Spree::Import` pipeline (implemented). Admin API v3 surface (create via direct-upload signed blob, `complete_mapping`, `retry_failed_rows`, nested failed-rows index, write-scope gating), `client.imports` SDK resource, dashboard-core `ImportButton` (per-context `<Can>` gating, upload Sheet) + full-window wizard dialog driven by an `?import=` search param, with history under `/settings/imports` (new `audit` settings-nav group). Status via API polling — explicitly no ActionCable/Turbo Streams in the SPA; legacy per-row live feed replaced by polled counters + paginated failed-rows table.diff --git a/docs/plans/5.6-dashboard-typed-plugin-routes.md b/docs/plans/5.6-dashboard-typed-plugin-routes.mdindex 57ccb56cc5..83cb8a81b0 100644--- a/docs/plans/5.6-dashboard-typed-plugin-routes.md+++ b/docs/plans/5.6-dashboard-typed-plugin-routes.md@@ -1,6 +1,6 @@# Dashboard Typed Plugin Routes (Build-Time Route Composition)-**Status:** In Progress (core implemented; published-tarball spike pending)+**Status:** In Progress (core + collision pre-flight + dep policy implemented; spike ✅ passed — remaining: preview-feedback review of registry deprecation)**Target:** Spree 5.6 (React Dashboard Developer Preview)**Depends on:** `5.6-project-layout-and-dashboard.md` (shell export, `packages/dashboard-starter`), `6.0-admin-spa.md`**Author:** Damian + Claude@@ -74,14 +74,25 @@ createRoot(document.getElementById('root')!).render(<Dashboard router={router} /- Starter typecheck passes with the example plugin's **cast-free** `<Link to="/$storeId/brands/$brandId" params={{ brandId }}>` — typed plugin links proven end-to-end.- The starter must declare `@tanstack/react-router` as a direct dependency: its gen file augments the router module, and augmentation only lands on the copy the host resolves.+### Published-tarball spike (✅ passed)++Packed the example plugin (`pnpm pack`) and installed it into a throwaway host via `file:<tarball>` — a **real extracted directory** in `node_modules`, not a workspace symlink (`@spree/*` were symlinked; the plugin was the variable under test). Ran a real `vite build` through `spreeDashboardPlugin()`:++- **Discovery resolved the plugin's `routesDir` to `…/node_modules/@spree/dashboard-plugin-example/src/routes`** and the generator composed both brands routes (46 total) with correct full paths/IDs; the emitted import points into `node_modules`.+- **No writes into the installed package** — route files' SHA-256 unchanged, committed `createFileRoute` literals intact. (The generator only rewrites a file whose literal disagrees with the composed path; committing the final literal keeps published packages read-only.)+- Route generation runs at `enforce: 'pre'` / `buildStart`, **before** Tailwind and bundling — confirmed by isolating it (a config without `spreeDashboardPlugin()`'s virtual module still generated the full tree before failing at the unrelated `virtual:spree-dashboard-plugins` bundle step).++Conclusion: published plugins are cleared. The `../node_modules/…` relative mount that `physical()` + `path.relative` produce resolves correctly through the generator in the mixed symlink-shell + tarball-plugin case (the harder resolution shape); a uniform registry install is strictly simpler.+## Migration Path1. *(shipped)* Shell: `@/` → relative imports, `createDashboardRouter` + `<Dashboard router>` exports, `Register` moved to `main.tsx`.2. *(shipped)* `@spree/dashboard/vite` route composition; the dashboard app itself and `packages/dashboard-starter` build through it.3. *(shipped)* `spree.dashboard.routes` marker; example plugin and CLI scaffold template migrated to file routes.-4. Docs: routes guide teaches file routes as the packaged-plugin path, registry for dynamic cases.-5. **Pending:** packed-tarball spike (generator parsing route files under real `node_modules`), then this pattern is cleared for published plugins.-6. Registry `routes:` stays indefinitely for in-app use; revisit whether to deprecate it for *packaged* plugins after the preview feedback round.+4. *(shipped)* Docs: routes guide teaches file routes as the packaged-plugin path, registry for dynamic cases.+5. *(shipped)* Packed-tarball spike passed — generator parses route files under real `node_modules` and never writes into the package; published plugins cleared.+6. *(shipped)* Cross-package route-collision pre-flight with package-named errors; TanStack dep classification fixed (`router-plugin` → dependency).+7. Registry `routes:` stays indefinitely for in-app use; revisit whether to deprecate it for *packaged* plugins after the preview feedback round.## Constraints on Current Work@@ -90,11 +101,14 @@ createRoot(document.getElementById('root')!).render(<Dashboard router={router} /- **Plugin scaffolds/examples put pages in `src/pages/`, route files in `src/routes/`**, and exclude `src/routes` from standalone tsc.- **Don't hand-edit `routeTree.gen.ts`** anywhere; it regenerates on every build.-## Open Questions+## Resolved Decisions-1. **Published-tarball behavior** — the generator must parse (and never write to) route files inside real `node_modules`. Expected fine (parse-only, literals committed correct); needs the spike before plugins publish.-2. **Route path collisions between plugins** — currently surfaces as a generator error naming files, not packages. Wrap with a friendlier message?-3. **Version coupling** — `@spree/dashboard` now depends on `@tanstack/router-plugin` + `@tanstack/virtual-file-routes`; pin policy relative to `@tanstack/react-router` majors/minors.+1. **Published-tarball behavior** — ✅ spike passed (see "Published-tarball spike" above). The generator parses route files under real `node_modules` and never writes into the package; published plugins are cleared.+2. **Route-path collisions** — ✅ implemented. `@spree/dashboard/vite` pre-flights collisions before invoking the generator (`assertNoRouteCollisions`, `src/vite/route-collisions.ts`) and throws an error naming the conflicting **packages** (the shell counts as `@spree/dashboard`), the route path, and each file — replacing TanStack's file-path-only `Conflicting configuration paths` error. Only cross-package collisions are pre-flighted; within-package duplicates stay the generator's to report. Covered by unit tests and verified live against two plugins colliding on `/$storeId/brands/`.+3. **TanStack dependency classification + pin policy** — ✅ settled:+ - `@tanstack/react-router` is a **peerDependency** (`^1.x`) — the host owns the singleton router; a single copy is required for the `Register` augmentation and the router instance. Matches `dashboard-core`/`dashboard-ui`. (Peer-only, no dev copy, per the repo's existing convention — the workspace root hoists it for in-repo build/test.)+ - `@tanstack/router-plugin` and `@tanstack/virtual-file-routes` are **dependencies** — they load through `@spree/dashboard/vite` at the host's `vite.config.ts` evaluation, so they must install transitively for consumers. (This is a fix: `router-plugin` was a devDependency, which would have left a published `@spree/dashboard`'s `/vite` import unresolved in host projects — verified via the starter, which builds with no direct `router-plugin` dep.)+ - **Pin ranges are per-package carets on the shared `1.x` major**, not a shared minor band: the three packages version independently (observed react-router 1.170, router-plugin 1.168, virtual-file-routes 1.162). Floors are set to the known-good lockfile versions. On a router major bump, bump all three together and re-run the composition + starter typecheck.## References