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.

Rewrite dashboard docs for readers outside the Spree codebase

Damian Legawiecd47c51c6e59c
diff --git a/docs/developer/dashboard/concepts.mdx b/docs/developer/dashboard/concepts.mdx
index 0da9c1c0c6..b0a4f396be 100644
--- a/docs/developer/dashboard/concepts.mdx
+++ b/docs/developer/dashboard/concepts.mdx
@@ -42,9 +42,9 @@ Five global, in-memory registries hold the things you add or modify:
| `settingsNav` | Settings sub-shell entries | `<SettingsSidebar>` |
| Route registry | Custom pages mounted under `/$storeId/*` | Catch-all dispatcher route |
| Slot registry | Components injected into named slots in built-in pages | `<Slot name="...">` |
-| Table registry | Columns, filters, row actions, bulk actions on built-in tables | `<ResourceTable>` |
+| Table registry | Columns (and their filters) on built-in list tables | `<ResourceTable>` |
-Each is a module singleton with `add`/`remove`/`update`/`insertBefore`/`insertAfter` mutators. The consumer components subscribe via `useSyncExternalStore`, so registering late still updates the UI on the next render.
+Each is a module singleton with mutators to add, remove, and patch entries (nav can also insert relative to an existing entry or nest children under one). The consumer components subscribe to changes, so registering late still updates the UI on the next render.
The facade `defineDashboardPlugin({ nav, routes, slots, … })` groups all five into one declarative call — convenient for plugins, optional for in-app customizations (you can call `nav.add()` directly).
@@ -84,7 +84,7 @@ This is why links work, deep-links restore filter state, and the browser back bu
## i18n is not optional
-The dashboard ships with English, German, French, Spanish, Portuguese, and a few more out of the box. Every label, placeholder, error message goes through `i18n.t()`. When you add a feature:
+The dashboard ships with English, German, French, Polish, Arabic, and Simplified Chinese out of the box. Every label, placeholder, error message goes through `i18n.t()`. When you add a feature:
1. Add the keys to your customization's `locales/en.json`
2. Register the bundle: `i18n.addResourceBundle('en', 'admin', bundle, true, false)`
@@ -94,7 +94,7 @@ The dashboard ships with English, German, French, Spanish, Portuguese, and a few
## Prefixed IDs everywhere
-The Admin API uses [Stripe-style prefixed IDs](/developer/api-reference/admin/overview#prefixed-ids): `prod_86Rf07xd4z`, `cust_k5nR8xLq`. The dashboard does too — URLs, hook params, table rows, SDK calls. Never coerce IDs to integers. Never strip the prefix. Pass them around as opaque strings.
+The Admin API uses [Stripe-style prefixed IDs](/api-reference/admin-api/introduction): `prod_86Rf07xd4z`, `cust_k5nR8xLq`. The dashboard does too — URLs, hook params, table rows, SDK calls. Never coerce IDs to integers. Never strip the prefix. Pass them around as opaque strings.
## Where to go next
diff --git a/docs/developer/dashboard/customization/backend.mdx b/docs/developer/dashboard/customization/backend.mdx
index 97e0e38451..0d5e301dd8 100644
--- a/docs/developer/dashboard/customization/backend.mdx
+++ b/docs/developer/dashboard/customization/backend.mdx
@@ -119,7 +119,7 @@ Pretty much always, for anything non-trivial. If you're filtering, sorting, or a
## Reference
-- [Admin API conventions](https://github.com/spree/spree/blob/main/docs/plans/6.0-admin-api.md)
+- [Admin API reference](/api-reference/admin-api/introduction) — auth, querying, errors, and every endpoint
- [`AdminClient.request`](https://github.com/spree/spree/blob/main/packages/admin-sdk/src/admin-client.ts) — full type
- [`SpreeError`](https://github.com/spree/spree/blob/main/packages/sdk-core/src/errors.ts)
- [`useResourceMutation`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/hooks/use-resource-mutation.ts)
diff --git a/docs/developer/dashboard/customization/navigation.mdx b/docs/developer/dashboard/customization/navigation.mdx
index b0ce0b8a67..e145a54455 100644
--- a/docs/developer/dashboard/customization/navigation.mdx
+++ b/docs/developer/dashboard/customization/navigation.mdx
@@ -15,16 +15,16 @@ import { nav } from '@spree/dashboard-core'
import { BarChartIcon } from 'lucide-react'
nav.add({
- key: 'reports',
- label: 'Reports',
- path: '/reports', // prefixed with /$storeId at render time
+ key: 'analytics',
+ label: 'Analytics',
+ path: '/analytics', // prefixed with /$storeId at render time
icon: BarChartIcon,
- position: 80,
+ position: 650,
subject: 'Spree::Order', // optional CanCanCan subject — hides item without read permission
})
```
-`position` controls ordering — built-ins use 100/200/300 to leave gaps. The default is 100.
+`position` controls ordering — built-ins use 100–600 (Home 100, Orders 200, Products 300, Customers 400, Promotions 500, Reports 600), leaving gaps to slot into. The default is 100. Keys must be unique, including against those built-in keys — duplicates throw at boot.
### Add via `defineDashboardPlugin`
@@ -35,8 +35,8 @@ import { defineDashboardPlugin } from '@spree/dashboard-core'
defineDashboardPlugin({
nav: [
- { key: 'reports', label: 'Reports', path: '/reports', icon: BarChartIcon, position: 80 },
- { key: 'segments', label: 'Segments', path: '/segments', icon: UsersIcon, position: 85 },
+ { key: 'analytics', label: 'Analytics', path: '/analytics', icon: BarChartIcon, position: 650 },
+ { key: 'segments', label: 'Segments', path: '/segments', icon: UsersIcon, position: 660 },
],
})
```
@@ -45,12 +45,13 @@ defineDashboardPlugin({
```ts
nav.add({
- key: 'reports',
- label: 'Reports',
+ key: 'analytics',
+ label: 'Analytics',
icon: BarChartIcon,
+ position: 650,
children: [
- { key: 'reports-sales', label: 'Sales', path: '/reports/sales' },
- { key: 'reports-inventory', label: 'Inventory', path: '/reports/inventory' },
+ { key: 'analytics.sales', label: 'Sales', path: '/analytics/sales' },
+ { key: 'analytics.traffic', label: 'Traffic', path: '/analytics/traffic' },
],
})
```
@@ -107,9 +108,9 @@ Or declaratively in `defineDashboardPlugin` — the `nav` object form adds, remo
```ts
defineDashboardPlugin({
nav: {
- add: [{ key: 'reviews', label: 'Reviews', path: '/reviews', position: 35 }],
- remove: ['gift-cards'],
- update: { products: { label: 'Catalog', position: 10 } },
+ add: [{ key: 'reviews', label: 'Reviews', path: '/reviews', position: 650 }],
+ remove: ['promotions'],
+ update: { products: { label: 'Catalog', position: 150 } },
},
})
```
@@ -184,12 +185,7 @@ Nav registrations run at module-load time. The sidebar reads via `useSyncExterna
- Registering before the sidebar mounts: works (the snapshot picks it up on first render)
- Registering after the sidebar mounts: also works (the store notifies subscribers)
-The only ordering rule is **i18n**: if you use `i18n.t('admin.foo.label')` for `label`, the i18n bootstrap must run first. Import order in `main.tsx`:
-
-```tsx
-import '@/i18n-setup' // base translations registered
-import '@/customizations' // your nav.add calls run; i18n.t resolves
-```
+The only ordering rule is **i18n**: if you use `i18n.t('admin.foo.label')` for `label`, your translation bundle must be registered first. The framework's own translations load before `src/plugins.ts` runs, so the rule reduces to: put your `i18n.addResourceBundle(...)` call at the top of `plugins.ts`, above the registrations that use it. See [Translations](/developer/dashboard/customization/translations).
## Reference
diff --git a/docs/developer/dashboard/customization/permissions.mdx b/docs/developer/dashboard/customization/permissions.mdx
index fab4696fda..5860c932bc 100644
--- a/docs/developer/dashboard/customization/permissions.mdx
+++ b/docs/developer/dashboard/customization/permissions.mdx
@@ -109,10 +109,9 @@ Spree::PermissionSets::DashboardManagement.class_eval do
end
```
-After that, `permissions.can('read', 'MyApp::Report')` resolves in the dashboard exactly like a first-party check — the abilities ship to the SPA via the `/api/v3/platform/users/me/permissions` endpoint at sign-in.
+After that, `permissions.can('read', 'MyApp::Report')` resolves in the dashboard exactly like a first-party check — the abilities ship to the dashboard with the current-user response (`GET /api/v3/admin/me`) at sign-in.
## Reference
- [`Permissions` interface](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/permissions.ts)
- [CanCanCan docs](https://github.com/CanCanCommunity/cancancan) — the Ruby ability definition language
-- [`6.0-admin-spa.md` permission section](https://github.com/spree/spree/blob/main/docs/plans/6.0-admin-spa.md) — the design that backs the SPA's permission system
diff --git a/docs/developer/dashboard/customization/quickstart.mdx b/docs/developer/dashboard/customization/quickstart.mdx
index 336faf9c26..b66b50f019 100644
--- a/docs/developer/dashboard/customization/quickstart.mdx
+++ b/docs/developer/dashboard/customization/quickstart.mdx
@@ -1,23 +1,21 @@
---
title: Quickstart
sidebarTitle: Quickstart
-description: Add your first customization to a Spree dashboard in under 5 minutes — no npm publishing, no Vite plugin, just a new file in your host app.
+description: Add your first customization to the Spree dashboard in under 5 minutes — no npm publishing, no build configuration, just one file in your dashboard app.
---
-This guide assumes you have a Spree 6.0 store already running. If not, scaffold one first:
+This guide assumes two things are running:
-```bash
-npx create-spree-app my-store
-cd my-store
-```
+1. A Spree API server (your Spree store's backend).
+2. Your dashboard app — the small Vite project that renders the admin. In a `create-spree-app` project it lives at `apps/dashboard/`; it can also be a standalone clone of the [dashboard starter](https://github.com/spree/dashboard-starter). Start it with `pnpm dev`.
-The scaffolded host has a dashboard app at `packages/dashboard/`. That's where customizations live. **You don't need to scaffold a plugin** — you're editing the host's own code.
+All customizations in this guide are edits to your dashboard app's own code. **You don't need to scaffold a plugin** — plugins are for [distributing features to other stores](/developer/dashboard/plugins/overview).
## The 30-second example
-Add a "Reports" item to the dashboard sidebar.
+Add an "Analytics" item to the dashboard sidebar.
-**Step 1.** Create `packages/dashboard/src/customizations.ts`:
+**Step 1.** Open `src/plugins.ts` — the starter ships this file already wired up — and register a nav entry:
```tsx
import { defineDashboardPlugin } from '@spree/dashboard-core'
@@ -25,84 +23,80 @@ import { BarChartIcon } from 'lucide-react'
defineDashboardPlugin({
nav: [{
- key: 'reports',
- label: 'Reports',
- path: '/reports',
+ key: 'analytics',
+ label: 'Analytics',
+ path: '/analytics',
icon: BarChartIcon,
- position: 80,
+ // Built-in entries use positions 100–600 (Home … Reports).
+ // 650 places Analytics after Reports, at the end.
+ position: 650,
}],
})
```
-**Step 2.** Import it from `packages/dashboard/src/main.tsx`, **before** the router mounts:
-
-```tsx
-import '@/i18n-setup'
-import '@/nav/default'
-import '@/nav/settings'
-import '@/customizations' // ← add this line
-// ...rest of bootstrap
-```
-
-**Step 3.** Restart the dev server. The sidebar now shows "Reports".
+**Step 2.** Save. The dev server hot-reloads and the sidebar now shows "Analytics".
-Clicking it goes to a "Page not found" screen — we registered the nav entry but no route. Let's fix that.
+Clicking it lands on a "Page not found" screen — we registered the nav entry but no page. Let's fix that.
## Add the page
-**Step 4.** Create the page component at `packages/dashboard/src/pages/reports.tsx`:
+**Step 3.** Create the page component at `src/pages/analytics.tsx`:
```tsx
import { PageHeader } from '@spree/dashboard-core'
import { ResourceLayout } from '@spree/dashboard-ui'
-export function ReportsPage() {
+export function AnalyticsPage() {
return (
<ResourceLayout
- header={<PageHeader title="Reports" subtitle="Store performance over time" />}
+ header={<PageHeader title="Analytics" subtitle="Store performance over time" />}
main={<p>Coming soon.</p>}
/>
)
}
```
-**Step 5.** Register the route in `customizations.ts`:
+**Step 4.** Register the route in `src/plugins.ts`:
```tsx
import { defineDashboardPlugin } from '@spree/dashboard-core'
import { BarChartIcon } from 'lucide-react'
-import { ReportsPage } from './pages/reports'
+import { AnalyticsPage } from './pages/analytics'
defineDashboardPlugin({
nav: [{
- key: 'reports',
- label: 'Reports',
- path: '/reports',
+ key: 'analytics',
+ label: 'Analytics',
+ path: '/analytics',
icon: BarChartIcon,
- position: 80,
+ position: 650,
}],
routes: [{
- key: 'reports',
- path: '/reports',
- component: ReportsPage,
+ key: 'analytics',
+ path: '/analytics',
+ component: AnalyticsPage,
}],
})
```
-Save. The dev server hot-reloads. Click "Reports" — your page renders.
+Save. Click "Analytics" — your page renders inside the dashboard chrome, at `/<store id>/analytics`.
+
+<Warning>
+Every `key` must be unique, including against the built-ins (`home`, `orders`, `products`, `customers`, `promotions`, `reports`, `settings`). Registering a duplicate key throws at boot with a message naming the conflict.
+</Warning>
## What just happened
-`defineDashboardPlugin` registers extensions against five module-singleton registries in `@spree/dashboard-core`: `nav`, `routes`, `slots`, `tables`, `settingsNav`. Because you imported `customizations.ts` from `main.tsx`, the registration runs at boot — before the router reads from the registry. Same APIs the marketplace plugins use.
+`defineDashboardPlugin` registers extensions against the dashboard's shared registries: `nav`, `routes`, `slots`, `tables`, and `settingsNav`. Your `src/plugins.ts` runs when the app boots (the starter's `main.tsx` imports it), so everything is registered before the first render. These are the exact same APIs distributable plugins use — the only difference is packaging.
-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.
+The custom route mounts under `/<store id>/analytics`. Routes registered this way are matched at navigation time, so they can even be registered lazily after boot.
-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.
+Building a **distributable plugin** rather than customizing your own app? Ship pages as [file routes](/developer/dashboard/customization/routes) instead — they compile into the app's route tree, so links to them 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
+- [Navigation](/developer/dashboard/customization/navigation) — sidebar entries, nesting under built-in menus, settings sub-nav, permission gating
- [Routes](/developer/dashboard/customization/routes) — path patterns, params, permission fallback
-- [Slots](/developer/dashboard/customization/slots) — inject widgets into core pages without forking them
-- [Tables](/developer/dashboard/customization/tables) — define your own list page or extend core tables
+- [Slots](/developer/dashboard/customization/slots) — inject widgets into built-in pages without forking them
+- [Tables](/developer/dashboard/customization/tables) — define your own list page or extend built-in tables
- [Translations](/developer/dashboard/customization/translations) — add i18n keys without colliding with the framework
diff --git a/docs/developer/dashboard/customization/routes.mdx b/docs/developer/dashboard/customization/routes.mdx
index b1a30d9d24..9eff396e55 100644
--- a/docs/developer/dashboard/customization/routes.mdx
+++ b/docs/developer/dashboard/customization/routes.mdx
@@ -175,7 +175,7 @@ The casts bypass TanStack Router's static type-checking (custom routes aren't in
## Order of operations
-Routes register at module-load time. The dispatcher reads from the registry on **every navigation**, so route registration is much more forgiving than nav: even a route registered after first render works as soon as the user navigates to it. That said, follow the same import order as everything else — `@/i18n-setup` first, then your customizations — so labels and i18n keys resolve correctly.
+Routes register at module-load time. The dispatcher reads from the registry on **every navigation**, so route registration is much more forgiving than nav: even a route registered after first render works as soon as the user navigates to it. The only ordering rule is the usual i18n one — register your translation bundle above any registration that calls `i18n.t(...)` (see [Translations](/developer/dashboard/customization/translations)).
## Reference
diff --git a/docs/developer/dashboard/customization/tables.mdx b/docs/developer/dashboard/customization/tables.mdx
index 0b3754a4e7..19a3b52b9c 100644
--- a/docs/developer/dashboard/customization/tables.mdx
+++ b/docs/developer/dashboard/customization/tables.mdx
@@ -1,153 +1,169 @@
---
title: Tables
sidebarTitle: Tables
-description: Add columns, bulk actions, row actions, and filters to built-in list tables (products, orders, customers, …) without forking them.
+description: Add, change, or remove columns on built-in list tables (products, orders, customers, …), or define a table for your own resource.
---
-Every list table in the dashboard is rendered by `<ResourceTable>` against a **table registry**. Built-in tables register their default columns and filters at boot; you can append to, modify, or remove entries from any table by its key (`products`, `orders`, `customers`, etc.).
+Every list page in the dashboard renders through `<ResourceTable>`, which reads its column definitions from a **table registry** keyed by table name (`products`, `orders`, `customers`, …). That gives you two levers:
-## Tour of the registry
+1. **Extend a built-in table** — add, patch, or remove columns (including their filters) without forking the page.
+2. **Define your own table** — declare columns once with `defineTable`, then render them with `<ResourceTable>` on your own page.
-```ts
-import { tables } from '@spree/dashboard-core'
-
-tables.products.columns.add(...) // append a column
-tables.products.columns.insertAfter('name', ...) // place explicitly
-tables.products.columns.remove('cost_price')
-tables.products.filters.add(...)
-tables.products.bulkActions.add(...)
-tables.products.rowActions.add(...)
-```
+## Add a column to a built-in table
-Each entry has a `key` so it can be referenced later for `update` or `remove`. Like nav, the registry is a singleton consumed via `useSyncExternalStore`, so late registration re-renders the table.
-
-## Add a column
+Imperatively, from `src/plugins.ts` (or a plugin entry):
```tsx
import { tables } from '@spree/dashboard-core'
-import type { Product } from '@spree/admin-sdk'
-tables.products.columns.add({
+tables.products.addColumn({
key: 'brand',
- header: 'Brand',
- cell: ({ row }) => row.brand?.name ?? '—',
- position: 250,
+ label: 'Brand',
+ default: true, // visible out of the box
+ render: (product) => product.brand?.name ?? '—',
})
```
-`cell` is a TanStack-Table `ColumnDef` cell renderer — `row` is fully typed as the resource (`Product`, `Order`, …) when you reach it from a typed registry key.
-
-### Sort + filter on a column
+Or declaratively through `defineDashboardPlugin` — same effect, grouped with your other extensions:
```tsx
-tables.products.columns.add({
- key: 'brand',
- header: 'Brand',
- cell: ({ row }) => row.brand?.name ?? '—',
- sortable: true,
- sortKey: 'brand_name', // becomes ?sort=brand_name when toggled
+defineDashboardPlugin({
+ tables: {
+ products: {
+ add: [{ key: 'brand', label: 'Brand', default: true, render: (p) => p.brand?.name ?? '—' }],
+ },
+ },
})
```
-For Ransack-backed filters, register against `filters` separately so the filter chip lives in the toolbar instead of the column header:
+New columns append after the existing ones. Column keys must be unique per table — adding a duplicate throws with a message telling you to use `updateColumn` instead.
+
+<Note>
+**Timing is taken care of.** Built-in tables register when their page first loads, which may be after your code runs. Mutations against a table that isn't registered yet are queued and replayed the moment it appears — and mutations against a table that never registers simply never fire. That means extending an optional feature's table is safe even when that feature isn't installed.
+</Note>
+
+## Modify or remove built-in columns
```tsx
-tables.products.filters.add({
- key: 'brand',
- label: 'Brand',
- type: 'multi-resource',
- resource: 'brands',
- ransackKey: 'brand_id_in',
-})
+tables.products.updateColumn('price', { label: 'Retail price' })
+tables.products.removeColumn('cost_price')
```
-## Add a row action
+Declaratively:
```tsx
-import { ArchiveIcon } from 'lucide-react'
-
-tables.products.rowActions.add({
- key: 'archive',
- label: 'Archive',
- icon: ArchiveIcon,
- onSelect: async ({ row }) => {
- await adminClient.products.update(row.id, { status: 'archived' })
+defineDashboardPlugin({
+ tables: {
+ products: {
+ update: { price: { label: 'Retail price' } },
+ remove: ['cost_price'],
+ },
},
- if: ({ row, permissions }) =>
- permissions.can('update', 'Spree::Product') && row.status !== 'archived',
})
```
-`if` runs per row — useful for hiding actions that don't apply (already archived, can't be deleted, etc.). When omitted, the action shows for every row.
+`updateColumn` patches shallowly — pass only the fields you want to change. `removeColumn` of an unknown key is a no-op.
-## Add a bulk action
+## Column definition
-Bulk actions appear in the toolbar above the table when rows are selected:
+```ts
+interface ColumnDef<T> {
+ key: string // unique per table; also the default Ransack sort/filter attribute
+ label: string // header text — use i18n.t(...) for translated labels
+ render?: (row: T) => ReactNode // cell renderer; defaults to rendering row[key] as text
+ className?: string // cell class (e.g. 'text-right tabular-nums')
+ default?: boolean // part of the visible column set out of the box
+ sortable?: boolean // header toggles Ransack sort on the attribute
+ filterable?: boolean // appears in the filter panel
+ ransackAttribute?: string // backend attribute when it differs from key
+ displayable?: boolean // set false for filter-only entries (no column rendered)
+}
+```
+
+### Filter types
+
+When a column is `filterable`, `filterType` decides which filter UI it gets:
+
+| `filterType` | Filter UI | Extra fields |
+|---|---|---|
+| `'string'` (default) | Text input with contains/equals operators | — |
+| `'boolean'` | Yes/no toggle | — |
+| `'number'`, `'currency'` | Numeric comparisons | — |
+| `'date'` | Date range picker (store-timezone aware) | — |
+| `'enum'` | Fixed option list | `filterOptions: [{ value, label }]` (required) |
+| `'resource'` | Multi-select autocomplete against another resource | `filterResource` (required) — `queryKey`, `search`, `hydrate`, `getOptionLabel` |
+| `'tags'` | Tag autocomplete | `taggableType` (required), e.g. `'Spree::Product'` |
+
+A `'resource'` filter searches as the admin types and resolves already-selected IDs back to labels on page reload:
```tsx
-tables.products.bulkActions.add({
- key: 'bulk-archive',
- label: 'Archive selected',
- icon: ArchiveIcon,
- variant: 'destructive',
- confirm: { title: 'Archive products?', description: 'You can restore them later.' },
- onSelect: async ({ rows }) => {
- await Promise.all(
- rows.map((row) => adminClient.products.update(row.id, { status: 'archived' })),
- )
+tables.products.addColumn({
+ key: 'brand_id',
+ label: 'Brand',
+ displayable: false, // filter only — no column in the table
+ filterable: true,
+ filterType: 'resource',
+ filterResource: {
+ queryKey: 'brands',
+ search: (query) => brandsClient.list({ q: { name_cont: query } }),
+ hydrate: (ids) => brandsClient.list({ q: { id_in: ids } }),
+ getOptionLabel: (brand) => brand.name,
},
})
```
-The `confirm` config opens a dialog before `onSelect` runs. Skip it for non-destructive actions.
+Filtering and sorting are executed by the Admin API (Ransack), not in the browser — `key` (or `ransackAttribute`) must be a filterable/sortable attribute the API allows.
-## Order columns explicitly
+## Define your own table
-`position` controls render order. Built-in columns leave gaps (100, 200, …) so you can slot in:
+For your own list page, declare the table once — typically right next to your `defineDashboardPlugin` call:
```tsx
-tables.products.columns.add({ key: 'brand', position: 150, /* ... */ })
+import { defineTable } from '@spree/dashboard-core'
+
+defineTable<Brand>('brands', {
+ title: 'Brands',
+ searchParam: 'search',
+ searchPlaceholder: 'Search by name…',
+ defaultSort: { field: 'name', direction: 'asc' },
+ emptyMessage: 'No brands yet',
+ columns: [
+ { key: 'name', label: 'Name', sortable: true, filterable: true, default: true },
+ { key: 'products_count', label: 'Products', default: true, className: 'text-right tabular-nums' },
+ { key: 'created_at', label: 'Created', sortable: true, default: false },
+ ],
+})
```
-Or pick a neighbour:
+Then render it from your page component:
```tsx
-tables.products.columns.insertAfter('name', { key: 'brand', /* ... */ })
-tables.products.columns.insertBefore('price', { key: 'tier', /* ... */ })
+<ResourceTable<Brand>
+ tableKey="brands" // which table definition to read
+ queryKey="brands" // TanStack Query cache key
+ queryFn={(params) => brandsClient.list(params)}
+ searchParams={searchParams}
+/>
```
-## Remove or modify a default column
+`<ResourceTable>` handles pagination, sorting, the filter panel, column visibility, and URL round-tripping of all of it. See [Routes](/developer/dashboard/customization/routes) for the page around it — the [example Brands plugin](https://github.com/spree/spree/tree/main/packages/dashboard-plugin-example) shows the complete wiring.
-```ts
-tables.products.columns.remove('cost_price')
+## Bulk actions, row actions, reordering
-tables.products.columns.update('price', {
- header: 'Retail price',
-})
-```
-
-The `update` patch is shallow — pass only the keys you want to change.
-
-## Permission-gating columns
-
-`if` on a column skips it for users without the matching permission:
+These are **props on `<ResourceTable>`**, composed by the page that renders the table:
```tsx
-tables.products.columns.add({
- key: 'cost_price',
- header: 'Cost',
- cell: ({ row }) => formatMoney(row.cost_price),
- if: ({ permissions }) => permissions.can('manage', 'Spree::Product'),
-})
+<ResourceTable<Brand>
+ // …
+ bulkActions={[{ key: 'archive', label: 'Archive selected', onSelect: async (rows) => { /* … */ } }]}
+ rowActions={(row) => <BrandRowMenu brand={row} />}
+/>
```
-This complements the backend, which omits `cost_price` from the serializer when the user can't see it.
-
-## Order of operations
-
-Same as nav: registry runs at module-load time, consumers re-render via `useSyncExternalStore`, late registration works. Make sure your `defineDashboardPlugin` call runs once — multiple calls add entries multiple times, which the dev-mode warning will catch.
+Use them freely on your own pages. They are **not registry-driven** — a plugin can't inject bulk or row actions into a built-in page's table today. If a built-in page needs an injection point, that's what [slots](/developer/dashboard/customization/slots) are for.
## Reference
-- [`TableRegistry`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/table-registry.ts) — full type including bulk-action and filter shapes
-- [`<ResourceTable>`](https://github.com/spree/spree/blob/main/packages/dashboard-ui/src/components/resource-table.tsx) — host component that reads from the registry
+- [`table-registry.ts`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/table-registry.ts) — `defineTable`, `tables`, the full `ColumnDef` union
+- [`<ResourceTable>`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/components/resource-table.tsx) — props for bulk actions, row actions, drag-reordering
+- [Example Brands plugin](https://github.com/spree/spree/tree/main/packages/dashboard-plugin-example) — a real `defineTable` + `<ResourceTable>` + products-column extension
diff --git a/docs/developer/dashboard/customization/translations.mdx b/docs/developer/dashboard/customization/translations.mdx
index 2c850db5af..98cd3fbcb1 100644
--- a/docs/developer/dashboard/customization/translations.mdx
+++ b/docs/developer/dashboard/customization/translations.mdx
@@ -90,12 +90,16 @@ Provide the localised string in `admin.errors.<resource>.<attribute>.<message_ke
## Order of operations
-Register translations **before** any code that calls `i18n.t()` at module-load time (registry labels, default nav items, etc.). The simplest pattern: do all i18n setup in a single `i18n-setup.ts` module, import it at the top of `main.tsx` before your customizations:
+Register translations **before** any code that calls `i18n.t()` at module-load time (registry labels, table titles, etc.). The framework's own bundles are loaded before your code runs, so the pattern is simply — top of the file:
```tsx
-// main.tsx
-import './i18n-setup' // i18n initialised + bundles added
-import './customizations' // nav.add, defineDashboardPlugin, …
+// src/plugins.ts (same pattern in a plugin package's entry module)
+import { defineDashboardPlugin, i18n } from '@spree/dashboard-core'
+import en from './locales/en.json'
+
+i18n.addResourceBundle('en', 'admin', en, true, false) // ① translations first
+
+defineDashboardPlugin({ /* ② registrations may now use i18n.t(...) */ })
```
## Reference
diff --git a/docs/developer/dashboard/overview.mdx b/docs/developer/dashboard/overview.mdx
index 9f8ecc60bc..d76f47f1bf 100644
--- a/docs/developer/dashboard/overview.mdx
+++ b/docs/developer/dashboard/overview.mdx
@@ -1,14 +1,14 @@
---
title: React Dashboard Overview
sidebarTitle: Overview
-description: How the React Dashboard — the Spree 6.0 admin — is structured, when to customize in-app, and when to ship a redistributable plugin.
+description: How the React Dashboard is structured, how to customize existing screens and how to build new features
---
<Info>
-The React Dashboard ships in **Spree 6.0** as a developer preview and replaces the Classic Admin (the Rails-rendered `spree/admin` engine). If you're on Spree 5.x today, the Classic Admin extension model is documented at [`/developer/admin/extending-ui`](/developer/admin/extending-ui).
+The React Dashboard is a Developer Preview — APIs may still change between releases. In Spree 6 it becomes the default admin interface.
</Info>
-The React Dashboard is a single-page application built on three packages:
+The React Dashboard is a single-page application (SPA) using Spree Admin API and built on three packages:
| Package | What it contains | When you touch it |
|---|---|---|
@@ -24,25 +24,20 @@ There are two ways to customize the dashboard. **Both use the same APIs** — th
### 1. Customize in your host app
-You're building a Spree store and want a "Featured products" page or a custom card on every product detail. Edit your host app's dashboard package directly:
+You're building a Spree store and want a "Featured products" page or a custom card on every product detail. Edit your dashboard app directly — it ships a `src/plugins.ts` file for exactly this (in a `create-spree-app` project the dashboard app lives at `apps/dashboard/`):
```tsx
-// packages/dashboard/src/main.tsx (your host app, scaffolded by create-spree-app)
-import './my-customizations' // ← your own file
-```
-
-```tsx
-// packages/dashboard/src/my-customizations.ts
+// src/plugins.ts — already imported by the app; just add your registrations
import { defineDashboardPlugin } from '@spree/dashboard-core'
import { MyAnalyticsPage } from './pages/analytics'
defineDashboardPlugin({
- nav: [{ key: 'analytics', label: 'Analytics', path: '/analytics' }],
+ nav: [{ key: 'analytics', label: 'Analytics', path: '/analytics', position: 650 }],
routes: [{ key: 'analytics', path: '/analytics', component: MyAnalyticsPage }],
})
```
-That's the entire setup. No npm publishing, no peer-deps, no Vite plugin registration — you're already inside the host's Vite build, so Tailwind already scans your source. Most teams stop here.
+That's the entire setup. No npm publishing, no peer dependencies, no build configuration — you're inside the app's own build, so styling and hot reload just work. Most teams stop here.
→ Start at the [**customization quickstart**](/developer/dashboard/customization/quickstart).
@@ -53,8 +48,8 @@ You're building a feature that multiple Spree stores will install — a Brands g
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.)
+- **Auto-discovery** — the dashboard's build finds every installed dependency carrying the `spree.dashboard.plugin` marker, activates it, and wires up its styling. Installing a plugin is `pnpm add` + a dev-server restart; nothing to edit. See [Distributing](/developer/dashboard/plugins/distributing) for how it works and the explicit-whitelist escape hatch.
+- **File routes** — a plugin ships its pages as TanStack file routes that get compiled into the app's route tree, so links to plugin pages are fully type-checked. See [Routes](/developer/dashboard/customization/routes). (In-app customizations use the simpler `routes:` registry instead, as above.)
- **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:
diff --git a/docs/developer/dashboard/plugins/distributing.mdx b/docs/developer/dashboard/plugins/distributing.mdx
index 31016c992c..8e7e6a6ab8 100644
--- a/docs/developer/dashboard/plugins/distributing.mdx
+++ b/docs/developer/dashboard/plugins/distributing.mdx
@@ -36,7 +36,7 @@ Plugins that take configuration (the `definePlugin(config)` factory pattern —
For tightly controlled environments (a host that wants explicit allowlist semantics, or a plugin you want to load conditionally), pass the names explicitly:
```ts
-// packages/dashboard/vite.config.ts
+// vite.config.ts (your dashboard app)
spreeDashboardPlugin({
plugins: ['@your-scope/your-plugin'], // disables auto-discovery
})
diff --git a/docs/developer/dashboard/plugins/overview.mdx b/docs/developer/dashboard/plugins/overview.mdx
index 333d79897f..8f2f65867f 100644
--- a/docs/developer/dashboard/plugins/overview.mdx
+++ b/docs/developer/dashboard/plugins/overview.mdx
@@ -4,7 +4,7 @@ sidebarTitle: Overview
description: Package dashboard customizations as a redistributable npm plugin. Read this if you're shipping a feature for *other* people's Spree projects — not your own.
---
-If you're customizing the dashboard for your own project, you don't need a plugin. Drop the same code into `packages/dashboard/src/customizations.ts` in your host app and skip this section entirely — start with the [Customization](/developer/dashboard/customization/quickstart) docs.
+If you're customizing the dashboard for your own project, you don't need a plugin. Drop the same code into `src/plugins.ts` in your dashboard app and skip this section entirely — start with the [Customization](/developer/dashboard/customization/quickstart) docs.
This section is for the ~10% of cases where you want to **distribute** dashboard extensions: as an open-source integration, an internal package shared across multiple host apps, or a SaaS-style commercial add-on.
@@ -18,7 +18,7 @@ A dashboard plugin is:
4. **Translations-aware** — your bundle ships JSON locale files and calls `i18n.addResourceBundle('en', 'admin', bundle, true, false)` on import.
5. **Possibly Rails-aware** — many plugins also ship a Rails engine alongside the dashboard package (new models, new API endpoints) so the dashboard has something to talk to.
-That's it. **Plugins use the exact same registries as in-app customizations.** Everything you can do in `packages/dashboard/src/customizations.ts` you can also do from inside a plugin entry-point. The split between "in-app" and "plugin" is about packaging and distribution, not capability.
+That's it. **Plugins use the exact same registries as in-app customizations.** Everything you can do in `src/plugins.ts` you can also do from inside a plugin entry-point. The split between "in-app" and "plugin" is about packaging and distribution, not capability.
## When to choose plugin over in-app
@@ -30,7 +30,7 @@ That's it. **Plugins use the exact same registries as in-app customizations.** E
| Commercial add-on with versioning + changelog | Plugin |
| One-off prototype, even at a client | In-app (you can extract later) |
-If you're not sure: start in-app. Lifting `customizations.ts` into a plugin package later is a half-hour refactor — moving in the other direction is more painful.
+If you're not sure: start in-app. Lifting `src/plugins.ts` into a plugin package later is a half-hour refactor — moving in the other direction is more painful.
## What's in this section
diff --git a/docs/developer/dashboard/plugins/publishing.mdx b/docs/developer/dashboard/plugins/publishing.mdx
index b9bdec330d..486a82d7a0 100644
--- a/docs/developer/dashboard/plugins/publishing.mdx
+++ b/docs/developer/dashboard/plugins/publishing.mdx
@@ -109,7 +109,7 @@ If you only ship `dist/` and your built code mangles class names (Tailwind can't
## Versioning with Changesets
-The Spree monorepo uses [Changesets](https://github.com/changesets/changesets); plugin authors don't have to, but it pairs well with peer-dep ranges. Workflow:
+Spree's own packages are versioned with [Changesets](https://github.com/changesets/changesets); plugin authors don't have to use it, but it pairs well with peer-dep ranges. Workflow:
```bash
pnpm changeset # describe what changed → writes a markdown file
diff --git a/docs/developer/dashboard/recipes/custom-form-field.mdx b/docs/developer/dashboard/recipes/custom-form-field.mdx
index e2976d2260..95d265e65e 100644
--- a/docs/developer/dashboard/recipes/custom-form-field.mdx
+++ b/docs/developer/dashboard/recipes/custom-form-field.mdx
@@ -26,7 +26,7 @@ And declared it as a permitted attribute on the Admin API serializer + controlle
Use a slot to inject your field into the product form's sidebar:
```tsx
-// packages/dashboard/src/customizations.ts
+// src/plugins.ts (in your dashboard app)
import { defineDashboardPlugin } from '@spree/dashboard-core'
import { TechSpecsField } from './fields/tech-specs-field'
@@ -48,7 +48,7 @@ If you don't see a slot at the right spot in the form, see [Slots catalog](/deve
The slot's context provides the React Hook Form instance for the page's form. Register your input against it:
```tsx
-// packages/dashboard/src/fields/tech-specs-field.tsx
+// src/fields/tech-specs-field.tsx
import {
Card, CardContent, CardHeader, CardTitle,
Field, FieldError, FieldLabel, Textarea,
@@ -102,7 +102,7 @@ A few patterns worth flagging:
If your customization adds client-side validation, extend the product form schema in the host app:
```ts
-// packages/dashboard/src/schemas/product.ts
+// src/schemas/product.ts
import { z } from 'zod'
export const productFormSchema = z
@@ -118,7 +118,7 @@ The form already uses `zodResolver(productFormSchema)`, so adding the key automa
## 4. Translations
```json
-// packages/dashboard/src/locales/en.json
+// src/locales/en.json
{
"fields": {
"product": {
diff --git a/docs/developer/dashboard/recipes/page-action-button.mdx b/docs/developer/dashboard/recipes/page-action-button.mdx
index d5f075f2fc..8971bc1fe2 100644
--- a/docs/developer/dashboard/recipes/page-action-button.mdx
+++ b/docs/developer/dashboard/recipes/page-action-button.mdx
@@ -16,7 +16,7 @@ This recipe shows both — and how to gate them by permission + resource state.
## A button in the actions row
```tsx
-// packages/dashboard/src/actions/send-invoice-button.tsx
+// src/actions/send-invoice-button.tsx
import { Button } from '@spree/dashboard-ui'
import { Send } from 'lucide-react'
import { useResourceMutation } from '@spree/dashboard-core'
@@ -53,7 +53,7 @@ export function SendInvoiceButton({ resource }: Props) {
Register it:
```ts
-// packages/dashboard/src/customizations.ts
+// src/plugins.ts (in your dashboard app)
import { defineDashboardPlugin } from '@spree/dashboard-core'
import { SendInvoiceButton } from './actions/send-invoice-button'
@@ -84,7 +84,7 @@ Keep both. The `if` check is cheap; the resource-state check needs the actual re
For secondary actions, use `page.actions_dropdown` and render `<DropdownMenuItem>`:
```tsx
-// packages/dashboard/src/actions/sync-to-erp-item.tsx
+// src/actions/sync-to-erp-item.tsx
import { DropdownMenuItem } from '@spree/dashboard-ui'
import { RefreshCw } from 'lucide-react'
import { useResourceMutation, adminClient } from '@spree/dashboard-core'
diff --git a/docs/developer/dashboard/recipes/sidebar-widget.mdx b/docs/developer/dashboard/recipes/sidebar-widget.mdx
index 178db25368..e4740b0d89 100644
--- a/docs/developer/dashboard/recipes/sidebar-widget.mdx
+++ b/docs/developer/dashboard/recipes/sidebar-widget.mdx
@@ -11,7 +11,7 @@ This recipe builds a "Loyalty status" card for the customer detail page: read-on
## The component
```tsx
-// packages/dashboard/src/widgets/loyalty-status-card.tsx
+// src/widgets/loyalty-status-card.tsx
import { useQuery } from '@tanstack/react-query'
import { adminClient, usePermissions, useStore } from '@spree/dashboard-core'
import {
@@ -88,7 +88,7 @@ Worth noting:
## Register the widget
```ts
-// packages/dashboard/src/customizations.ts
+// src/plugins.ts (in your dashboard app)
import { defineDashboardPlugin } from '@spree/dashboard-core'
import { LoyaltyStatusCard } from './widgets/loyalty-status-card'
diff --git a/docs/developer/dashboard/slots-catalog.mdx b/docs/developer/dashboard/slots-catalog.mdx
index 187e83bd91..919e0c614d 100644
--- a/docs/developer/dashboard/slots-catalog.mdx
+++ b/docs/developer/dashboard/slots-catalog.mdx
@@ -4,7 +4,7 @@ sidebarTitle: Slots catalog
description: Every named slot the dashboard renders today. Each entry lists the host page, the slot name, and the context the slot's components receive.
---
-This is the canonical list of slots the dashboard currently exposes. To rebuild it locally: `grep -rn '<Slot name=' packages/dashboard/src packages/dashboard-core/src` and cross-reference each call site for its `context` prop.
+This is the canonical list of slots the dashboard currently exposes. The source of truth is the `<Slot name="…">` call sites in the dashboard source (linked under Reference below); each entry here records the host page, the slot name, and the context your component receives.
If you need a new injection point in a built-in page, open a PR adding `<Slot name="..." context={...} />` and a documentation entry here — that's the contract for new slots.
diff --git a/docs/developer/sdk/admin/quickstart.mdx b/docs/developer/sdk/admin/quickstart.mdx
index fec02bf8a6..b0f3f15d19 100644
--- a/docs/developer/sdk/admin/quickstart.mdx
+++ b/docs/developer/sdk/admin/quickstart.mdx
@@ -49,7 +49,7 @@ const product = await client.products.create({
})
```
-Every method is fully typed — responses use `Admin`-prefixed types generated from the API serializers:
+Every method is fully typed — responses use types generated from the API serializers:
```typescript
import type { Order, PaginatedResponse } from '@spree/admin-sdk'
diff --git a/docs/docs.json b/docs/docs.json
index 738ae7c167..c53ba549fd 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -297,46 +297,6 @@
"developer/tutorial/testing"
]
},
- {
- "group": "React Dashboard",
- "icon": "gauge",
- "pages": [
- "developer/dashboard/overview",
- "developer/dashboard/concepts",
- "developer/dashboard/public-api",
- {
- "group": "Customization",
- "pages": [
- "developer/dashboard/customization/quickstart",
- "developer/dashboard/customization/navigation",
- "developer/dashboard/customization/routes",
- "developer/dashboard/customization/slots",
- "developer/dashboard/customization/tables",
- "developer/dashboard/customization/translations",
- "developer/dashboard/customization/permissions",
- "developer/dashboard/customization/backend"
- ]
- },
- {
- "group": "Recipes",
- "pages": [
- "developer/dashboard/recipes/custom-form-field",
- "developer/dashboard/recipes/page-action-button",
- "developer/dashboard/recipes/sidebar-widget"
- ]
- },
- {
- "group": "Plugins",
- "pages": [
- "developer/dashboard/plugins/overview",
- "developer/dashboard/plugins/scaffolding",
- "developer/dashboard/plugins/publishing",
- "developer/dashboard/plugins/distributing"
- ]
- },
- "developer/dashboard/slots-catalog"
- ]
- },
{
"group": "Classic Admin",
"icon": "ruby",
@@ -428,6 +388,57 @@
}
]
},
+ {
+ "item": "Dashboard",
+ "icon": "gauge",
+ "description": "React dashboard",
+ "groups": [
+ {
+ "group": "Overview",
+ "pages": [
+ "developer/dashboard/overview",
+ "developer/dashboard/concepts",
+ "developer/dashboard/public-api"
+ ]
+ },
+ {
+ "group": "Customization",
+ "pages": [
+ "developer/dashboard/customization/quickstart",
+ "developer/dashboard/customization/navigation",
+ "developer/dashboard/customization/routes",
+ "developer/dashboard/customization/slots",
+ "developer/dashboard/customization/tables",
+ "developer/dashboard/customization/translations",
+ "developer/dashboard/customization/permissions",
+ "developer/dashboard/customization/backend"
+ ]
+ },
+ {
+ "group": "Recipes",
+ "pages": [
+ "developer/dashboard/recipes/custom-form-field",
+ "developer/dashboard/recipes/page-action-button",
+ "developer/dashboard/recipes/sidebar-widget"
+ ]
+ },
+ {
+ "group": "Plugins",
+ "pages": [
+ "developer/dashboard/plugins/overview",
+ "developer/dashboard/plugins/scaffolding",
+ "developer/dashboard/plugins/publishing",
+ "developer/dashboard/plugins/distributing"
+ ]
+ },
+ {
+ "group": "Slots Catalog",
+ "pages": [
+ "developer/dashboard/slots-catalog"
+ ]
+ }
+ ]
+ },
{
"item": "Operations",
"icon": "server",