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.

Migrate the example plugin to file routes

Damian Legawiec561ff56d543d
diff --git a/packages/dashboard-plugin-example/package.json b/packages/dashboard-plugin-example/package.json
index 23d67c09ba..3b908d6d49 100644
--- a/packages/dashboard-plugin-example/package.json
+++ b/packages/dashboard-plugin-example/package.json
@@ -23,7 +23,8 @@
},
"spree": {
"dashboard": {
- "plugin": true
+ "plugin": true,
+ "routes": "./src/routes"
}
},
"peerDependencies": {
diff --git a/packages/dashboard-plugin-example/src/index.tsx b/packages/dashboard-plugin-example/src/index.tsx
index feafeb6581..84ba80c69b 100644
--- a/packages/dashboard-plugin-example/src/index.tsx
+++ b/packages/dashboard-plugin-example/src/index.tsx
@@ -33,8 +33,6 @@ import { Link } from '@tanstack/react-router'
import { PackageIcon } from 'lucide-react'
import { brandsClient } from './client'
import en from './locales/en.json'
-import { BrandDetailPage } from './routes/brand-detail'
-import { BrandsListPage } from './routes/brands-list'
import { ProductBrandCard } from './slots/product-brand-card'
import type { Brand } from './types'
@@ -66,12 +64,12 @@ defineTable<Brand>('brands', {
sortable: true,
filterable: true,
default: true,
+ // Typed against the host's generated route tree — the plugin's file
+ // routes (src/routes/) are compiled into it, so no casts needed.
render: (b) => (
<Link
- to={'/$storeId/brands/$brandId' as string}
- // Registry routes aren't in the generated route tree, so the param
- // object needs the same escape hatch as `to`.
- params={{ brandId: b.id } as never}
+ to="/$storeId/brands/$brandId"
+ params={{ brandId: b.id }}
className="font-medium text-foreground no-underline"
>
{b.name}
@@ -121,20 +119,10 @@ defineDashboardPlugin({
subject: 'Spree::Brand',
},
],
- routes: [
- {
- key: 'brands',
- path: '/brands',
- component: BrandsListPage,
- subject: 'Spree::Brand',
- },
- {
- key: 'brand-detail',
- path: '/brands/$brandId',
- component: BrandDetailPage,
- subject: 'Spree::Brand',
- },
- ],
+ // Routes are NOT registered here: this plugin ships file routes in
+ // src/routes/ (declared via the package.json marker), which the host build
+ // compiles into its typed route tree. The `routes:` registry option remains
+ // for dynamic, host-app cases — see the routes customization guide.
slots: {
'product.form_sidebar': [
{
diff --git a/packages/dashboard-plugin-example/src/pages/brand-detail.tsx b/packages/dashboard-plugin-example/src/pages/brand-detail.tsx
index 737a9c17f6..cadecb965b 100644
--- a/packages/dashboard-plugin-example/src/pages/brand-detail.tsx
+++ b/packages/dashboard-plugin-example/src/pages/brand-detail.tsx
@@ -1,8 +1,6 @@
/**
- * Brand detail page. Mounted at `/$storeId/brands/$brandId` via the plugin's
- * route registration in `index.tsx` — the canonical example of a plugin route
- * with a path param. The catch-all dispatcher extracts `$brandId` from the
- * URL and hands it to us via `params`.
+ * Brand detail page, rendered by the `brands.$brandId` file route with the
+ * path param already extracted.
*/
import { PageHeader } from '@spree/dashboard-core'
import { Card, CardContent, CardHeader, CardTitle, Skeleton } from '@spree/dashboard-ui'
@@ -11,12 +9,11 @@ import { useTranslation } from 'react-i18next'
import { brandsClient } from '../client'
interface BrandDetailPageProps {
- params: Record<string, string>
+ brandId: string
}
-export function BrandDetailPage({ params }: BrandDetailPageProps) {
+export function BrandDetailPage({ brandId }: BrandDetailPageProps) {
const { t } = useTranslation()
- const brandId = params.brandId
const { data: brand, isLoading } = useQuery({
queryKey: ['plugin-brands', 'brand', brandId],
diff --git a/packages/dashboard-plugin-example/src/pages/brands-list.tsx b/packages/dashboard-plugin-example/src/pages/brands-list.tsx
index f9bc5952c5..95dd2f2b75 100644
--- a/packages/dashboard-plugin-example/src/pages/brands-list.tsx
+++ b/packages/dashboard-plugin-example/src/pages/brands-list.tsx
@@ -1,16 +1,11 @@
/**
- * Brands index page. Mounted at `/$storeId/brands` via the plugin's route
- * registration in `index.tsx`. Uses the dashboard's `<ResourceTable>` for
- * filtering, sorting, pagination, and bulk-action chrome — the same UX as
- * core's Products/Customers/Orders pages.
+ * Brands index page, rendered by the `brands.index` file route. Uses the
+ * dashboard's `<ResourceTable>` for filtering, sorting, pagination, and
+ * bulk-action chrome — the same UX as core's Products/Customers/Orders pages.
*
* The table's columns and filters are declared via `defineTable('brands', ...)`
* in `../index.tsx` (alongside the plugin entry); ResourceTable reads from
* that registry by tableKey.
- *
- * Plugin route components receive `{ params, storeId, searchParams }` from
- * the catch-all dispatcher. We forward `searchParams` straight to
- * ResourceTable so filter/sort/pagination round-trip through the URL.
*/
import { PageHeader, type ResourceSearch, ResourceTable } from '@spree/dashboard-core'
import { Button, ResourceLayout } from '@spree/dashboard-ui'
@@ -20,7 +15,7 @@ import { brandsClient } from '../client'
import type { Brand } from '../types'
interface BrandsListPageProps {
- searchParams: Record<string, unknown>
+ searchParams: ResourceSearch
}
export function BrandsListPage({ searchParams }: BrandsListPageProps) {
@@ -48,11 +43,7 @@ export function BrandsListPage({ searchParams }: BrandsListPageProps) {
// (its internal builder doesn't know what each table's API accepts).
// We narrow to our client's known param shape at the boundary.
queryFn={(params) => brandsClient.list(params as Record<string, never>)}
- // The catch-all dispatcher passes searchParams as a generic record
- // because it can't know each plugin's parsed shape. ResourceTable
- // expects a Zod-validated `ResourceSearch`; defaults fill in any
- // missing fields, so the cast is safe at the boundary.
- searchParams={searchParams as ResourceSearch}
+ searchParams={searchParams}
/>
}
/>
diff --git a/packages/dashboard-plugin-example/src/routes/brands.$brandId.tsx b/packages/dashboard-plugin-example/src/routes/brands.$brandId.tsx
new file mode 100644
index 0000000000..d29d0c8fe1
--- /dev/null
+++ b/packages/dashboard-plugin-example/src/routes/brands.$brandId.tsx
@@ -0,0 +1,16 @@
+/**
+ * File route for the brand detail page — demonstrates a path param
+ * (`$brandId`) as a first-class, typed route: `<Link>`s to it are checked
+ * against the host's generated route tree, no casts needed.
+ */
+import { createFileRoute } from '@tanstack/react-router'
+import { BrandDetailPage } from '../pages/brand-detail'
+
+export const Route = createFileRoute('/_authenticated/$storeId/brands/$brandId')({
+ component: BrandDetailRoute,
+})
+
+function BrandDetailRoute() {
+ const { brandId } = Route.useParams()
+ return <BrandDetailPage brandId={brandId} />
+}
diff --git a/packages/dashboard-plugin-example/src/routes/brands.index.tsx b/packages/dashboard-plugin-example/src/routes/brands.index.tsx
new file mode 100644
index 0000000000..6daa76309c
--- /dev/null
+++ b/packages/dashboard-plugin-example/src/routes/brands.index.tsx
@@ -0,0 +1,23 @@
+/**
+ * File route for the brands list — compiled into the host's route tree by
+ * `spreeDashboardPlugin()` (this directory is declared via the package.json
+ * marker: `"spree": { "dashboard": { "routes": "./src/routes" } }`).
+ *
+ * The path literal is the FINAL composed path: plugin routes mount under the
+ * dashboard's `_authenticated/$storeId` layout. Committing the correct
+ * literal matters — the route generator verifies it and would rewrite the
+ * file otherwise.
+ */
+import { resourceSearchSchema } from '@spree/dashboard-core'
+import { createFileRoute } from '@tanstack/react-router'
+import { BrandsListPage } from '../pages/brands-list'
+
+export const Route = createFileRoute('/_authenticated/$storeId/brands/')({
+ validateSearch: resourceSearchSchema,
+ component: BrandsRoute,
+})
+
+function BrandsRoute() {
+ const searchParams = Route.useSearch()
+ return <BrandsListPage searchParams={searchParams} />
+}
diff --git a/packages/dashboard-plugin-example/tsconfig.json b/packages/dashboard-plugin-example/tsconfig.json
index fbb2ea3e56..9a926fd6c6 100644
--- a/packages/dashboard-plugin-example/tsconfig.json
+++ b/packages/dashboard-plugin-example/tsconfig.json
@@ -21,5 +21,6 @@
"noUncheckedSideEffectImports": true,
"resolveJsonModule": true
},
- "include": ["src"]
+ "include": ["src"],
+ "exclude": ["src/routes"]
}