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
Document file routes and route-collision behavior
Damian Legawiec81b67dcae88c
diff --git a/docs/developer/dashboard/customization/quickstart.mdx b/docs/developer/dashboard/customization/quickstart.mdxindex c90ea34a7e..336faf9c26 100644--- a/docs/developer/dashboard/customization/quickstart.mdx+++ b/docs/developer/dashboard/customization/quickstart.mdx@@ -97,6 +97,8 @@ Save. The dev server hot-reloads. Click "Reports" — your page renders.The custom route mounts under `/$storeId/reports`. The dashboard's catch-all dispatcher matches the URL splat against the route registry on every navigation, so late registration (lazy-imported features) still works without reconfiguring the router.+Building a **distributable plugin** rather than customizing your own app? Ship pages as [file routes](/developer/dashboard/customization/routes) instead — they compile into the host's typed route tree, so links are type-checked. The registry form shown here is for in-app customization.+## Next steps- [Navigation](/developer/dashboard/customization/navigation) — sidebar entries, settings sub-nav, children, permissions gatingdiff --git a/docs/developer/dashboard/customization/routes.mdx b/docs/developer/dashboard/customization/routes.mdxindex 083d7dc280..b1a30d9d24 100644--- a/docs/developer/dashboard/customization/routes.mdx+++ b/docs/developer/dashboard/customization/routes.mdx@@ -50,6 +50,19 @@ Links to file routes are fully typed — no casts:<Link to="/$storeId/brands/$brandId" params={{ brandId: brand.id }}>view</Link>```+### Route collisions++Two packages can't own the same route path. If a plugin declares a path that another plugin — or a built-in dashboard page — already claims, the build fails before generating the tree with an error naming both **packages**, the path, and each file:++```+Dashboard route collision.+Route "/_authenticated/$storeId/brands/" is declared by more than one package:+ - @acme/brands (…/node_modules/@acme/brands/src/routes/brands.index.tsx)+ - @other/brands (…/node_modules/@other/brands/src/routes/brands.index.tsx)+```++Rename one of the routes, or drop the plugin that shouldn't own it. (Duplicate paths *within* a single package are reported by the TanStack generator instead — that's an authoring bug in one package.)+## Runtime route registry (in-app & dynamic)Register from your host app's `plugins.ts` (or a plugin that genuinely needs runtime registration):diff --git a/docs/developer/dashboard/overview.mdx b/docs/developer/dashboard/overview.mdxindex 0c369d1a93..9f8ecc60bc 100644--- a/docs/developer/dashboard/overview.mdx+++ b/docs/developer/dashboard/overview.mdx@@ -54,6 +54,7 @@ This adds three concerns on top of in-app customization:- **Peer-dependency rules** so your plugin's `@spree/dashboard-core` resolves to the host's instance (registries are module singletons — see [Publishing](/developer/dashboard/plugins/publishing))- **Auto-discovery** — `spreeDashboardPlugin()` reads the host's `package.json` deps, picks up any with the `spree.dashboard.plugin` marker, and both activates them (via the `virtual:spree-dashboard-plugins` module the app entry imports) and wires Tailwind scanning. Installing is `pnpm add` + dev-server restart. See [Distributing](/developer/dashboard/plugins/distributing) for details and the manual-whitelist escape hatch.+- **File routes** — a plugin ships its pages as TanStack file routes (the `spree.dashboard.routes` marker) that the host build compiles into its typed route tree, so links to plugin pages are type-checked with no casts. See [Routes](/developer/dashboard/customization/routes). (In-app customizations use the runtime `routes:` registry instead, as above — no build step, no marker.)- **A backend half** — a Rails extension gem that ships the API endpoints your dashboard plugin callsThe `@spree/cli` scaffolds the dashboard half for you: