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
Harden the plugin route dispatcher and registry
Damian Legawiec2e82cc5ac7f1
diff --git a/docs/developer/dashboard/customization/routes.mdx b/docs/developer/dashboard/customization/routes.mdxindex a5302ff4b6..aa7dc64481 100644--- a/docs/developer/dashboard/customization/routes.mdx+++ b/docs/developer/dashboard/customization/routes.mdx@@ -109,7 +109,7 @@ import { Link } from '@tanstack/react-router'</Link>```-The `as string` cast bypasses TanStack Router's static type-checking for the path (because custom routes aren't in the generated route tree). Params are passed positionally.+The `as string` cast bypasses TanStack Router's static type-checking for the path (because custom routes aren't in the generated route tree). Params are passed as a keyed object — each key fills the matching `$name` token.## Order of operationsdiff --git a/docs/developer/dashboard/customization/translations.mdx b/docs/developer/dashboard/customization/translations.mdxindex 637cfb7c95..2c850db5af 100644--- a/docs/developer/dashboard/customization/translations.mdx+++ b/docs/developer/dashboard/customization/translations.mdx@@ -59,7 +59,7 @@ nav.add({})```-Note: `i18n.t` resolves at the call site, so it's snapshot at registration time. If the user changes language without a reload, sidebar labels updates automatically because the sidebar re-renders on locale change. If you stash the resolved string elsewhere, refresh it on the i18n `languageChanged` event.+Note: `i18n.t` resolves at the call site, so the label is a snapshot taken at registration time. Registry entries store plain strings — if the user switches language without a reload, registered labels keep their old language until re-registered. Components that call `useTranslation()` re-render on locale change; registry labels don't. If that matters for your entry, re-register it on the i18n `languageChanged` event.## Field-key conventiondiff --git a/packages/dashboard-core/src/lib/route-registry.ts b/packages/dashboard-core/src/lib/route-registry.tsindex b034eb184f..a0a5fc54ce 100644--- a/packages/dashboard-core/src/lib/route-registry.ts+++ b/packages/dashboard-core/src/lib/route-registry.ts@@ -109,6 +109,10 @@ export function usePluginRoutes(): readonly RouteEntry[] {* Path patterns support TanStack-style `$param` tokens. A pattern segment* of `$brandId` matches any non-empty URL segment and binds it to* `params.brandId`.+ *+ * More-specific patterns win regardless of registration order: `/brands/new`+ * beats `/brands/$brandId` for the URL `/brands/new` because it has fewer+ * dynamic segments.*/export function matchPluginRoute(splat: string,@@ -116,7 +120,10 @@ export function matchPluginRoute(): { entry: RouteEntry; params: Record<string, string> } | null {// Normalize: strip leading slash, drop empty trailing segments.const urlSegments = splat.replace(/^\/+/, '').split('/').filter(Boolean)- for (const entry of routes) {+ const bySpecificity = [...routes].sort(+ (a, b) => countDynamicSegments(a.path) - countDynamicSegments(b.path),+ )+ for (const entry of bySpecificity) {const patternSegments = entry.path.replace(/^\/+/, '').split('/').filter(Boolean)if (patternSegments.length !== urlSegments.length) continue@@ -137,6 +144,13 @@ export function matchPluginRoute(return null}+function countDynamicSegments(path: string): number {+ return path+ .replace(/^\/+/, '')+ .split('/')+ .filter((segment) => segment.startsWith('$')).length+}+/** Test-only: clear the registry. */export function __resetPluginRoutes(): void {entries.length = 0diff --git a/packages/dashboard-core/src/plugin.ts b/packages/dashboard-core/src/plugin.tsindex 8fddac7409..62c38d1e07 100644--- a/packages/dashboard-core/src/plugin.ts+++ b/packages/dashboard-core/src/plugin.ts@@ -74,8 +74,9 @@ export interface DashboardPluginConfig {/*** Register all the extensions in `config` against the dashboard's registries.- * Safe to call multiple times — each registry enforces uniqueness on its own- * keys, so a duplicate `key`/`id` throws with a useful message.+ * Call it once per plugin entry module — each registry enforces uniqueness on+ * its keys, so re-running the same config (or colliding with another plugin's+ * `key`/`id`) throws with a useful message rather than double-registering.** Plugins typically call this once from their entry module (e.g.* `src/index.ts`). The dashboard app imports plugin entries during bootstrap.diff --git a/packages/dashboard-core/tests/route-registry.test.ts b/packages/dashboard-core/tests/route-registry.test.tsnew file mode 100644index 0000000000..04299cd14c--- /dev/null+++ b/packages/dashboard-core/tests/route-registry.test.ts@@ -0,0 +1,34 @@+import { describe, expect, it } from 'vitest'+import { matchPluginRoute, type RouteEntry } from '../src/lib/route-registry'++function entry(key: string, path: string): RouteEntry {+ return { key, path, component: () => null }+}++describe('matchPluginRoute', () => {+ it('matches static segments exactly', () => {+ const routes = [entry('brands', '/brands')]+ expect(matchPluginRoute('brands', routes)?.entry.key).toBe('brands')+ expect(matchPluginRoute('/brands', routes)?.entry.key).toBe('brands')+ expect(matchPluginRoute('brand', routes)).toBeNull()+ expect(matchPluginRoute('brands/extra', routes)).toBeNull()+ })++ it('extracts $param segments', () => {+ const routes = [entry('brand-detail', '/brands/$brandId')]+ const match = matchPluginRoute('brands/br_123', routes)+ expect(match?.entry.key).toBe('brand-detail')+ expect(match?.params).toEqual({ brandId: 'br_123' })+ })++ it('prefers static patterns over $param patterns regardless of registration order', () => {+ const routes = [entry('brand-detail', '/brands/$brandId'), entry('brands-new', '/brands/new')]+ expect(matchPluginRoute('brands/new', routes)?.entry.key).toBe('brands-new')+ expect(matchPluginRoute('brands/br_123', routes)?.entry.key).toBe('brand-detail')+ })++ it('returns null when nothing matches', () => {+ expect(matchPluginRoute('unknown', [entry('brands', '/brands')])).toBeNull()+ expect(matchPluginRoute('', [entry('brands', '/brands')])).toBeNull()+ })+})diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.jsonindex 0542ea1a69..6016eecab8 100644--- a/packages/dashboard/src/locales/ar.json+++ b/packages/dashboard/src/locales/ar.json@@ -89,6 +89,13 @@"app_name": "Spree Admin","powered_by": "مدعوم من Spree Commerce"},+ "errors": {+ "not_found_title": "الصفحة غير موجودة",+ "not_found_description": "الصفحة التي تبحث عنها غير موجودة.",+ "forbidden_title": "غير مصرح",+ "forbidden_description": "ليس لديك إذن لعرض هذه الصفحة.",+ "plugin_route_title": "تعذّر عرض هذه الصفحة"+ },"nav": {"home": "الرئيسية","account": "الحساب",diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.jsonindex ade40f35fc..c7cdc5af4b 100644--- a/packages/dashboard/src/locales/de.json+++ b/packages/dashboard/src/locales/de.json@@ -41,6 +41,13 @@"app_name": "Spree Admin","powered_by": "Bereitgestellt von Spree Commerce"},+ "errors": {+ "not_found_title": "Seite nicht gefunden",+ "not_found_description": "Die gesuchte Seite existiert nicht.",+ "forbidden_title": "Nicht berechtigt",+ "forbidden_description": "Sie haben keine Berechtigung, diese Seite anzuzeigen.",+ "plugin_route_title": "Diese Seite konnte nicht dargestellt werden"+ },"nav": {"home": "Startseite","account": "Konto",diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.jsonindex a11546a5ee..46491b86a1 100644--- a/packages/dashboard/src/locales/en.json+++ b/packages/dashboard/src/locales/en.json@@ -89,6 +89,13 @@"app_name": "Spree Admin","powered_by": "Powered by Spree Commerce"},+ "errors": {+ "not_found_title": "Page not found",+ "not_found_description": "The page you’re looking for doesn’t exist.",+ "forbidden_title": "Not authorized",+ "forbidden_description": "You don’t have permission to view this page.",+ "plugin_route_title": "This page failed to render"+ },"nav": {"home": "Home","account": "Account",diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.jsonindex 0f51588a8b..4e072457b1 100644--- a/packages/dashboard/src/locales/fr.json+++ b/packages/dashboard/src/locales/fr.json@@ -41,6 +41,13 @@"app_name": "Administration Spree","powered_by": "Propulsé par Spree Commerce"},+ "errors": {+ "not_found_title": "Page introuvable",+ "not_found_description": "La page que vous recherchez n’existe pas.",+ "forbidden_title": "Non autorisé",+ "forbidden_description": "Vous n’avez pas la permission de voir cette page.",+ "plugin_route_title": "Le rendu de cette page a échoué"+ },"nav": {"home": "Accueil","account": "Compte",diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.jsonindex e08cd307f7..333a8e8e90 100644--- a/packages/dashboard/src/locales/pl.json+++ b/packages/dashboard/src/locales/pl.json@@ -41,6 +41,13 @@"app_name": "Panel administracyjny Spree","powered_by": "Obsługiwane przez Spree Commerce"},+ "errors": {+ "not_found_title": "Nie znaleziono strony",+ "not_found_description": "Strona, której szukasz, nie istnieje.",+ "forbidden_title": "Brak uprawnień",+ "forbidden_description": "Nie masz uprawnień do wyświetlenia tej strony.",+ "plugin_route_title": "Nie udało się wyświetlić tej strony"+ },"nav": {"home": "Strona główna","account": "Konto",diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.jsonindex 977c86198e..f220d1eb3f 100644--- a/packages/dashboard/src/locales/zh-CN.json+++ b/packages/dashboard/src/locales/zh-CN.json@@ -89,6 +89,13 @@"app_name": "Spree 管理后台","powered_by": "由 Spree Commerce 提供支持"},+ "errors": {+ "not_found_title": "页面未找到",+ "not_found_description": "您访问的页面不存在。",+ "forbidden_title": "未授权",+ "forbidden_description": "您没有权限查看此页面。",+ "plugin_route_title": "此页面渲染失败"+ },"nav": {"home": "首页","account": "账户",diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/$.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/$.tsxindex 82264d1ec9..0dbf2c5d53 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/$.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/$.tsx@@ -17,8 +17,21 @@ import { useTranslation } from 'react-i18next'export const Route = createFileRoute('/_authenticated/$storeId/$')({component: PluginRouteDispatcher,+ // Contain plugin render errors to this route — a broken third-party page+ // shouldn't take down the dashboard shell.+ errorComponent: PluginRouteError,})+function PluginRouteError({ error }: { error: Error }) {+ const { t } = useTranslation()+ return (+ <ErrorState+ title={t('admin.errors.plugin_route_title', { defaultValue: 'This page failed to render' })}+ description={error.message}+ />+ )+}+function PluginRouteDispatcher() {const { storeId, _splat } = Route.useParams() as { storeId: string; _splat?: string }const searchParams = Route.useSearch() as Record<string, unknown>