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
Align the dashboard docs with the facade and the starter layout (#14668)
Damian Legawieca40e2a6c0c63
diff --git a/docs/developer/dashboard/concepts.mdx b/docs/developer/dashboard/concepts.mdxindex ade8b6b765..2b74f3d4ec 100644--- a/docs/developer/dashboard/concepts.mdx+++ b/docs/developer/dashboard/concepts.mdx@@ -30,7 +30,9 @@ The dashboard is a **Single Page Application**: one HTML page, all routing clien@spree/dashboard ─ app shell: routes, resource hooks, locales, vite config```-[Overview](/developer/dashboard/overview) covers the split in more detail. The short version: **`-ui`** has no providers or hooks (data comes via props); **`-core`** is the extension API and runtime services; **`-dashboard`** is the deployable app shell. Plugins and customizations consume `-core` and `-ui`, never the app shell.+[Overview](/developer/dashboard/overview) covers the split in more detail. The short version: **`-ui`** has no providers or hooks (data comes via props); **`-core`** is the extension API and runtime services; **`-dashboard`** is the deployable app shell.++The split matters when you publish a plugin: it consumes `-core` and `-ui` and never the app shell, which it plugs into rather than ships. In your own dashboard app the distinction is noise, so `@spree/dashboard` re-exports both — one import, and you never have to work out which package a given export lives in.## How customization plugs in@@ -53,7 +55,7 @@ The facade `defineDashboardPlugin({ nav, routes, slots, … })` groups all fiveThe signed-in admin's identity and abilities are exposed via three providers wrapping the app:- `<AuthProvider>` — the current admin user; `useAuth()` returns `{ user, signIn, signOut, … }`-- `<PermissionProvider>` — CanCanCan abilities; `usePermissions()` returns `{ can, cannot }`+- `<PermissionProvider>` — CanCanCan abilities; `usePermissions()` returns `{ permissions, rules, isLoading }`, and the checks live on `permissions.can(...)`- `<StoreProvider>` — current store + timezone + currency; `useStore()` returns `{ storeId, store, … }`When you write a custom page or hook, pull from these. **Never reach into local state for identity** — it changes on store switch or session refresh, and the providers wire all that for you.diff --git a/docs/developer/dashboard/customization/backend.mdx b/docs/developer/dashboard/customization/backend.mdxindex 99a72c70b9..17ac74c539 100644--- a/docs/developer/dashboard/customization/backend.mdx+++ b/docs/developer/dashboard/customization/backend.mdx@@ -54,13 +54,16 @@ Resource methods are just `request<T>()` calls with the right path + types pre-bThe dashboard's data layer is React-Query — every `useFoo` hook is `useQuery({ queryKey, queryFn })` over an SDK call. Follow the same pattern for your own data:```ts-import { adminClient } from '@spree/dashboard'+import { adminClient, useResourceKey } from '@spree/dashboard'import { useQuery } from '@tanstack/react-query'import type { AdminBrand } from './types'export function useBrands(params?: { search?: string }) {return useQuery({- queryKey: ['brands', params],+ // `useResourceKey` scopes the key to the current store. A bare+ // `['brands', params]` key would serve one store's rows to another+ // after a store switch.+ queryKey: useResourceKey('brands', params),queryFn: () =>adminClient.request<{ data: AdminBrand[] }>('GET', '/brands', { params }),staleTime: 30_000,diff --git a/docs/developer/dashboard/customization/navigation.mdx b/docs/developer/dashboard/customization/navigation.mdxindex e6cee92cbc..4287d9269b 100644--- a/docs/developer/dashboard/customization/navigation.mdx+++ b/docs/developer/dashboard/customization/navigation.mdx@@ -28,7 +28,7 @@ nav.add({})```-`position` controls ordering — built-ins use 100–600 (Home 100, Orders 200, Products 300, Customers 400, Promotions 500, Reports 600; a conditional Getting Started entry sits at 50), leaving gaps to slot into. The default is 100. Keys must be unique, including against the built-in keys (`getting-started`, `home`, `orders`, `products`, `customers`, `promotions`, `reports`, `settings`) — duplicates throw at boot.+`position` controls ordering — built-ins run 50–600 (Getting Started 50 when shown, Home 100, Orders 200, Products 300, Inventory 350, Customers 400, Sellers 450, Loyalty 475, Promotions 500, Reports 600), leaving gaps to slot into. The default is 100. Keys must be unique, including against the built-in keys (`getting-started`, `home`, `orders`, `products`, `inventory`, `customers`, `sellers`, `loyalty`, `promotions`, `reports`, `settings`) — duplicates throw at boot.### Add via `defineDashboardPlugin`diff --git a/docs/developer/dashboard/customization/quickstart.mdx b/docs/developer/dashboard/customization/quickstart.mdxindex 7774a8f33d..e103389ea5 100644--- a/docs/developer/dashboard/customization/quickstart.mdx+++ b/docs/developer/dashboard/customization/quickstart.mdx@@ -81,7 +81,7 @@ defineDashboardPlugin({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 (`getting-started`, `home`, `orders`, `products`, `customers`, `promotions`, `reports`, `settings`). Registering a duplicate key throws at boot with a message naming the conflict.+Every `key` must be unique, including against the built-ins (`getting-started`, `home`, `orders`, `products`, `inventory`, `customers`, `sellers`, `loyalty`, `promotions`, `reports`, `settings`). Registering a duplicate key throws at boot with a message naming the conflict.</Warning>## What just happeneddiff --git a/docs/developer/dashboard/overview.mdx b/docs/developer/dashboard/overview.mdxindex defbebfb80..d292be0f54 100644--- a/docs/developer/dashboard/overview.mdx+++ b/docs/developer/dashboard/overview.mdx@@ -8,7 +8,7 @@ description: Learn about the Spree React Dashboard architecture and how to custoThe React Dashboard is currently a **Developer Preview** — APIs may still change between releases. It is becoming the default Admin interface.</Info>-The React Dashboard is a React single-page application (SPA) that talks to the [Spree Admin API](/api-reference/admin-api). It can be distributed with the Spree API or as a standalone npm package, and it can be extended with plugins. The dashboard is built with modern React libraries and patterns, including:+The React Dashboard is a React single-page application (SPA) that talks to the [Spree Admin API](/api-reference/admin-api/introduction). It can be distributed with the Spree API or as a standalone npm package, and it can be extended with plugins. The dashboard is built with modern React libraries and patterns, including:| Layer | Choice ||---|---|@@ -37,7 +37,7 @@ Most customization uses the registries in `@spree/dashboard-core` to add nav ent**In your own dashboard app, import from `@spree/dashboard`.** It re-exports both packages, so you never have to work out which one an export lives in. A distributed plugin is the exception: it imports `@spree/dashboard-core` and `@spree/dashboard-ui` directly, because it plugs into the shell rather than shipping it.-You can also built your own dashboard using `@spree/dashboard-ui` primitives and `@spree/dashboard-core` registries, if you want to replace the default dashboard entirely. This is rare — most teams just add a few pages or cards to the existing dashboard.+You can also build your own dashboard using `@spree/dashboard-ui` primitives and `@spree/dashboard-core` registries, if you want to replace the default dashboard entirely. This is rare — most teams just add a few pages or cards to the existing dashboard.## Get the dashboarddiff --git a/docs/developer/dashboard/plugins/distributing.mdx b/docs/developer/dashboard/plugins/distributing.mdxindex 8e7e6a6ab8..e555976fa2 100644--- a/docs/developer/dashboard/plugins/distributing.mdx+++ b/docs/developer/dashboard/plugins/distributing.mdx@@ -120,7 +120,7 @@ The registries are global singletons, so a key collision is the consumer's probl- **Namespace locale keys** — `admin.acme_brands.title` not `admin.brands.title`.- **Namespace API paths** — your Rails engine should mount under `/api/v3/admin/acme/...`, not `/api/v3/admin/brands` (which collides with core Brands if it ever ships).-The dashboard logs a warning in dev mode when two registry entries share a key. That's the consumer's signal that two plugins are stepping on each other — and it falls back to "last-registered wins", which is rarely what either plugin wanted.+Registering a key that already exists throws at boot, with a message naming the conflict. That is deliberate: a silently shadowed entry would leave the consumer with a plugin that half works, where a failure at startup points straight at the two plugins stepping on each other.## Distribution channelsdiff --git a/docs/developer/dashboard/public-api.mdx b/docs/developer/dashboard/public-api.mdxindex ef23abf156..40bef5eb01 100644--- a/docs/developer/dashboard/public-api.mdx+++ b/docs/developer/dashboard/public-api.mdx@@ -4,7 +4,7 @@ sidebarTitle: Public APIdescription: Every importable symbol the dashboard exposes — components, hooks, registries, providers, and the SDK client. Treat this as the surface you can safely depend on.----The dashboard is structured as three packages, each with a documented public surface. **Anything not listed here is internal** — don't import it via `@spree/dashboard-core/src/internal/...`, because we'll move or rename it without a deprecation cycle.+The dashboard is structured as three packages. This page lists the symbols we commit to keeping — **treat anything not listed as internal**, liable to move or be renamed without a deprecation cycle, even where the barrel happens to export it today. Never reach past a package entry point into `@spree/dashboard-core/src/...`.## `@spree/dashboard-core`@@ -51,7 +51,7 @@ import {// Page chromePageHeader,PageTabs,- TopBar,+ MobileTopBar,AppSidebar,SettingsSidebar,Slot,@@ -92,6 +92,7 @@ import {useCustomFields,useDirectUpload, // ActiveStorage direct uploadsuseExport, // CSV export job lifecycle+ useResourceKey, // store-scoped query key — use it for every custom queryuseResourceMutation, // useMutation wrapper with 422 handlinguseHostForm, // the built-in form a slot widget renders inside (throws when absent)useOptionalHostForm, // same, but null when the page has no host formdiff --git a/docs/developer/dashboard/recipes/attribute-end-to-end.mdx b/docs/developer/dashboard/recipes/attribute-end-to-end.mdxindex 34707b6fed..34da924779 100644--- a/docs/developer/dashboard/recipes/attribute-end-to-end.mdx+++ b/docs/developer/dashboard/recipes/attribute-end-to-end.mdx@@ -14,7 +14,7 @@ It's the full version of the [custom form field recipe](/developer/dashboard/rec## First: should this be a custom field instead?-**Default to a [custom field definition](/developer/dashboard/recipes/custom-form-field#path-a-custom-field-definition--no-code).** It needs zero code — declare the field, and the product form renders and saves it. That covers most plugin data and everything merchants define themselves.+**Default to a [custom field definition](/developer/dashboard/recipes/custom-form-field#path-a-custom-field-definition-no-code).** It needs zero code — declare the field, and the product form renders and saves it. That covers most plugin data and everything merchants define themselves.Graduate to a real database column only when the attribute needs **list operations or database guarantees**:@@ -90,7 +90,7 @@ Add a Rails validation while you're here (`validates :lead_time_days, numericali```tsx// src/plugins.ts (or a plugin's entry module)import { defineDashboardPlugin, i18n } from '@spree/dashboard'-import { LeadTimeCard } from './fields/lead-time-card'+import { LeadTimeCard } from './slots/lead-time-card'import en from './locales/en.json'i18n.addResourceBundle('en', 'translation', en, true, true)@@ -124,7 +124,7 @@ defineDashboardPlugin({The form widget binds to the host form — no `<form>` of its own, no save button:```tsx-// src/fields/lead-time-card.tsx+// src/slots/lead-time-card.tsximport { Card, CardContent, CardHeader, CardTitle, Field, FieldError, FieldLabel, Input, useHostForm } from '@spree/dashboard'import { useTranslation } from 'react-i18next'diff --git a/docs/developer/dashboard/recipes/custom-form-field.mdx b/docs/developer/dashboard/recipes/custom-form-field.mdxindex 6859e6e1fd..fd4bab8c6f 100644--- a/docs/developer/dashboard/recipes/custom-form-field.mdx+++ b/docs/developer/dashboard/recipes/custom-form-field.mdx@@ -93,7 +93,7 @@ defineDashboardPlugin({The `product.form_sidebar` slot renders inside the product form. Bind your input to the host form with `useHostForm()` — no `<form>` of your own, no save button:```tsx-// src/fields/tech-specs-card.tsx+// src/slots/tech-specs-card.tsximport {Card,CardContent,diff --git a/docs/developer/dashboard/recipes/page-action-button.mdx b/docs/developer/dashboard/recipes/page-action-button.mdxindex 53fc6289b3..665c16b95d 100644--- a/docs/developer/dashboard/recipes/page-action-button.mdx+++ b/docs/developer/dashboard/recipes/page-action-button.mdx@@ -21,7 +21,7 @@ import { Button, adminClient, usePermissions, useResourceMutation } from '@spreeimport { Send } from 'lucide-react'interface Props {- resource: { id: string; state: string } // Order+ resource: { id: string; status: string } // Order}export function SendInvoiceButton({ resource }: Props) {@@ -34,7 +34,7 @@ export function SendInvoiceButton({ resource }: Props) {// Only show to users who can act, and only on completed orders.if (!permissions.can('update', 'Spree::Order')) return null- if (resource.state !== 'complete') return null+ if (resource.status !== 'placed') return nullreturn (<Buttondiff --git a/docs/developer/dashboard/recipes/sidebar-widget.mdx b/docs/developer/dashboard/recipes/sidebar-widget.mdxindex 40764dba89..8533b3b5fa 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-// src/widgets/loyalty-status-card.tsx+// src/slots/loyalty-status-card.tsximport { useQuery } from '@tanstack/react-query'import {adminClient,@@ -101,7 +101,7 @@ Worth noting:```ts// src/plugins.ts (in your dashboard app)import { defineDashboardPlugin } from '@spree/dashboard'-import { LoyaltyStatusCard } from './widgets/loyalty-status-card'+import { LoyaltyStatusCard } from './slots/loyalty-status-card'defineDashboardPlugin({slots: {diff --git a/docs/developer/dashboard/slots-catalog.mdx b/docs/developer/dashboard/slots-catalog.mdxindex e0b098d578..8f1d33da32 100644--- a/docs/developer/dashboard/slots-catalog.mdx+++ b/docs/developer/dashboard/slots-catalog.mdx@@ -89,6 +89,66 @@ The resource detail pages each render a slot below their built-in cards. The con| Context | `{ customer }` — the full `Customer` record || Host form | No — the page edits through sheets; widgets save via their own API calls |+### `collection.form_sidebar`++| Where | Collection detail page (`products/collections/$collectionId`), end of the sidebar column |+|---|---|+| Use | Collection-scoped cards — merchandising rules, feed settings, external sync state |+| Context | `{ collection }` — the `Collection` record |+| Host form | **Yes** — form key `collection` |++### `company.form_main`++| Where | Company detail page, end of the main column |+|---|---|+| Use | B2B account cards — credit terms, approval settings, external account references |+| Context | `{ company, kind, canEdit }` — `kind` is the company's own `kind`, `canEdit` whether the viewer may write |+| Host form | No — the widget owns its persistence |++### `company.form_sidebar`++| Where | Company detail page, end of the sidebar column |+|---|---|+| Use | Narrow company-scoped cards alongside the main form |+| Context | `{ company, kind, canEdit }` |+| Host form | No |++## Seller panel slots++Rendered by the marketplace seller panel (`@spree/seller-dashboard`) rather than the admin dashboard, and registered the same way.++### `seller.form_main`++| Where | Seller detail page, end of the main column |+|---|---|+| Use | Seller-scoped cards — payout configuration, onboarding state, compliance records |+| Context | `{ seller, canEdit }` |+| Host form | No |++### `seller.form_sidebar`++| Where | Seller detail page, end of the sidebar column |+|---|---|+| Use | Narrow seller-scoped cards |+| Context | `{ seller, canEdit }` |+| Host form | No |++### `seller.team.actions`++| Where | Seller team screen, in the header's action area |+|---|---|+| Use | Team-level actions — bulk invite, export, an external directory sync |+| Context | `{ sellerId }` |+| Host form | No |++### `seller.team.after`++| Where | Seller team screen, below the member list |+|---|---|+| Use | Anything that belongs under the team — audit log, role explainer, seat usage |+| Context | `{ sellerId }` |+| Host form | No |+## Page tabs slot### `page.tabs` (default)diff --git a/packages/dashboard-starter/AGENTS.md b/packages/dashboard-starter/AGENTS.mdindex ebef571468..c87ada08e4 100644--- a/packages/dashboard-starter/AGENTS.md+++ b/packages/dashboard-starter/AGENTS.md@@ -31,6 +31,7 @@ uses internally.| `src/hooks/` | Admin API wrappers | `use-brands.ts` || `src/tables/` | `defineTable` calls | `brands.tsx` || `src/schemas/` | Zod schema + `FormValues` | `brand.ts` |+| `src/slots/` | Widgets injected into built-in pages | `product-brand-card.tsx` || `src/locales/` | Your `admin.*` translation keys | `en.json` |Adding a resource touches one file in each directory. Keep `plugins.ts` a mapdiff --git a/packages/dashboard-starter/README.md b/packages/dashboard-starter/README.mdindex 24cba918bf..ebdcf56df0 100644--- a/packages/dashboard-starter/README.md+++ b/packages/dashboard-starter/README.md@@ -51,6 +51,8 @@ src/├── hooks/ one file per resource use-brands.ts├── tables/ one file per resource brands.tsx├── schemas/ one file per resource brand.ts+├── slots/ widgets injected into product-brand-card.tsx+│ built-in pages└── locales/ your translations en.json```@@ -101,6 +103,11 @@ type (`Product`, `Order`) in a form-values type — React Hook Form walks everynested key and the SDK's object graph overflows the TypeScript compiler.Inline a short single-file schema instead.+**`slots/`** — components you inject into pages the dashboard already+renders, one file per widget. A slot widget takes its data from the slot's+context and, on a page with a host form, binds its inputs to that form with+`useHostForm()` rather than saving anything itself.+**`locales/`** — every visible string goes through i18next, including columnlabels and button text. Keys live under a top-level `admin` object. Load thebundle once at the top of `plugins.ts`:diff --git a/packages/dashboard-starter/src/slots/.gitkeep b/packages/dashboard-starter/src/slots/.gitkeepnew file mode 100644index 0000000000..e69de29bb2diff --git a/packages/seller-dashboard-starter/AGENTS.md b/packages/seller-dashboard-starter/AGENTS.mdindex 22a707169b..1007d8b671 100644--- a/packages/seller-dashboard-starter/AGENTS.md+++ b/packages/seller-dashboard-starter/AGENTS.md@@ -34,6 +34,7 @@ uses internally.| `src/hooks/` | Admin API wrappers | `use-brands.ts` || `src/tables/` | `defineTable` calls | `brands.tsx` || `src/schemas/` | Zod schema + `FormValues` | `brand.ts` |+| `src/slots/` | Widgets injected into built-in pages | `seller-payout-card.tsx` || `src/locales/` | Your `admin.*` translation keys | `en.json` |Adding a resource touches one file in each directory. Keep `plugins.ts` a mapdiff --git a/packages/seller-dashboard-starter/src/slots/.gitkeep b/packages/seller-dashboard-starter/src/slots/.gitkeepnew file mode 100644index 0000000000..e69de29bb2