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.

Harden the plugin route dispatcher and registry

Damian Legawiec2e82cc5ac7f1
diff --git a/docs/developer/dashboard/customization/routes.mdx b/docs/developer/dashboard/customization/routes.mdx
index 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 operations
diff --git a/docs/developer/dashboard/customization/translations.mdx b/docs/developer/dashboard/customization/translations.mdx
index 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 convention
diff --git a/packages/dashboard-core/src/lib/route-registry.ts b/packages/dashboard-core/src/lib/route-registry.ts
index 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 = 0
diff --git a/packages/dashboard-core/src/plugin.ts b/packages/dashboard-core/src/plugin.ts
index 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.ts
new file mode 100644
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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/$.tsx
index 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>