Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Document file routes and route-collision behavior

Damian Legawiec81b67dcae88c
diff --git a/docs/developer/dashboard/customization/quickstart.mdx b/docs/developer/dashboard/customization/quickstart.mdx
index 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 gating
diff --git a/docs/developer/dashboard/customization/routes.mdx b/docs/developer/dashboard/customization/routes.mdx
index 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.mdx
index 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 calls
The `@spree/cli` scaffolds the dashboard half for you: