@spree/docs 0.1.122 → 0.1.123

package/dist/api-reference/admin-api/endpoints.md

@@ -366,7 +366,7 @@ Endpoints marked — are exempt from scope checks (authentication and session en
 
 | Method | Path | Required scope | Summary |
 |---|---|---|---|
-| `POST` | `/translations/batch` | *write_<resource> for every resource type in the batch (for API-key authentication)* | Batch upsert translations |
+| `POST` | `/translations/batch` | `write_*` (eg. `write_products`) for every resource type in the batch (for API-key authentication) | Batch upsert translations |
 
 ## Webhook endpoints
 

package/dist/developer/dashboard/concepts.md

@@ -0,0 +1,103 @@
+---
+title: Concepts
+sidebarTitle: Concepts
+description: The mental model — what the dashboard is built on, how the pieces fit together, and what you need to know about each layer before you start customizing.
+---
+
+This page is a five-minute orientation for the dashboard's technology choices and how they cooperate. If you're already familiar with React + TanStack + Tailwind, skim it for the Spree-specific bits and move on.
+
+## Tech stack at a glance
+
+| Layer | What we use | Why it matters |
+|---|---|---|
+| Build | [Vite](https://vitejs.dev/) | Fast HMR, dev server, source consumption of TS/TSX |
+| UI runtime | [React 19](https://react.dev/) | Components, hooks, suspense |
+| Routing | [TanStack Router](https://tanstack.com/router) (file-based) | Type-safe URLs, nested layouts, search params |
+| Data | [TanStack Query v5](https://tanstack.com/query) | Caching, refetch, mutation tracking |
+| Forms | [React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/) | Uncontrolled inputs + schema validation |
+| Styling | [Tailwind v4](https://tailwindcss.com/) + [shadcn/ui](https://ui.shadcn.com/) + [Base UI](https://base-ui.com/) | Utility classes + headless primitives |
+| i18n | [i18next](https://www.i18next.com/) | Translations, fallback chains |
+| Lint/format | [Biome](https://biomejs.dev/) | ESLint + Prettier in one tool |
+| HTTP | [`@spree/admin-sdk`](https://www.npmjs.com/package/@spree/admin-sdk) | Typed Admin API client |
+
+The dashboard is a **Single Page Application**: one HTML page, all routing client-side. No Rails views, no Turbo, no server-rendered partials. Everything the user sees comes from React components fetching JSON from `/api/v3/admin/*`.
+
+## The three-package split
+
+```
+@spree/dashboard-ui   ─ design system: shadcn primitives + headless compounds + tokens
+@spree/dashboard-core ─ framework: registries + providers + hooks + SDK client + plugin facade
+@spree/dashboard      ─ app shell: routes, resource hooks, locales, vite config
+```
+
+[Overview](overview.md) 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.
+
+## How customization plugs in
+
+Five global, in-memory registries hold the things you add or modify:
+
+| Registry | Adds | Surfaced by |
+|---|---|---|
+| `nav` | Sidebar entries | `<AppSidebar>` |
+| `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 (and their filters) on built-in list tables | `<ResourceTable>` |
+
+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).
+
+## Auth, context, providers
+
+The 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 }`
+- `<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.
+
+## Data fetching
+
+Every screen in the dashboard follows the same pattern:
+
+```
+adminClient (SDK)
+   ↓ called inside
+useFoo (custom hook wrapping useQuery)
+   ↓ consumed by
+<FooList /> (component renders cached data, owns no fetching logic)
+```
+
+Wrap SDK calls in custom hooks under `src/hooks/`, never call `adminClient` directly from components. See [Backend integration](customization/backend.md) for the full pattern, error mapping, and the `useResourceMutation` helper that wires up 422 handling.
+
+## URL = state
+
+The dashboard treats the URL as the single source of truth for page state:
+
+- Filters, sort, page number → URL search params
+- Selected row → URL path param
+- "Sheet open?" → URL search param (`?edit=prod_xxx`)
+
+This is why links work, deep-links restore filter state, and the browser back button does the right thing. When you build a custom page, follow the same rule — don't stash filter state in React state where it's invisible to bookmarks and analytics.
+
+## i18n is not optional
+
+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', 'translation', bundle, true, true)`
+3. Use `useTranslation()` in components and `i18n.t()` at registration sites
+
+[Translations](customization/translations.md) covers the field-key convention.
+
+## Prefixed IDs everywhere
+
+The Admin API uses [Stripe-style prefixed IDs](../../api-reference/admin-api/introduction.md): `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
+
+- [Public API](public-api.md) — what's importable from `@spree/dashboard-core` / `-ui` / `-dashboard`
+- [Customization Quickstart](customization/quickstart.md) — first nav entry in 30 seconds
+- [Recipes](recipes/custom-form-field.md) — focused walkthroughs for common extension shapes

package/dist/developer/dashboard/customization/backend.md

@@ -0,0 +1,126 @@
+---
+title: Backend integration
+sidebarTitle: Backend integration
+description: Talk to your own (or Spree's) Admin API from the dashboard — typed SDK calls, custom endpoints, prefixed IDs, error handling, and React-Query hooks.
+---
+
+The dashboard never reaches into Rails models or fetches HTML. All data flows through `@spree/admin-sdk` — a typed Admin API client. This page covers the patterns: calling existing endpoints, adding new ones, handling errors, and wrapping it all in React-Query hooks for caching.
+
+## The `adminClient`
+
+The SPA boots a single `adminClient` instance and exposes it from `@spree/dashboard-core`. Resource methods follow `client.<resource>.<verb>()`:
+
+```ts
+import { adminClient } from '@spree/dashboard-core'
+
+await adminClient.products.list({ filter: { name_cont: 'shirt' } })
+await adminClient.products.get('prod_86Rf07xd4z', { expand: ['variants'] })
+await adminClient.products.create({ name: 'New product' })
+await adminClient.products.update('prod_86Rf07xd4z', { name: 'Renamed' })
+await adminClient.products.delete('prod_86Rf07xd4z')
+```
+
+All IDs are [prefixed](../../../api-reference/admin-api/querying.md) — pass them in, get them out. The SDK never coerces to integers.
+
+## Custom endpoints
+
+When you've added an endpoint to `spree/api` that the SDK doesn't model yet (host-app routes, an in-development feature, a custom controller), use the public `request<T>()` escape hatch:
+
+```ts
+import type { AdminBrand } from './types'
+
+const data = await adminClient.request<{ data: AdminBrand[] }>(
+  'GET',
+  '/brands',
+  { params: { 'filter[name_cont]': 'nike' } },
+)
+```
+
+It accepts:
+
+- `method` — `'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE'`
+- `path` — relative to `/api/v3/admin` (so `/brands` hits `/api/v3/admin/brands`)
+- `body` — JSON-stringified for non-GET requests
+- `params` — query string
+
+Resource methods are just `request<T>()` calls with the right path + types pre-bound. When you publish your customization or generate types from your serializer, you can promote the inline call to a typed wrapper.
+
+## React-Query hooks
+
+The 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-core'
+import { useQuery } from '@tanstack/react-query'
+import type { AdminBrand } from './types'
+
+export function useBrands(params?: { search?: string }) {
+  return useQuery({
+    queryKey: ['brands', params],
+    queryFn: () =>
+      adminClient.request<{ data: AdminBrand[] }>('GET', '/brands', { params }),
+    staleTime: 30_000,
+  })
+}
+```
+
+For mutations, prefer the existing `useResourceMutation` helper — it wires up the SDK's error shape, the 422 silencer, and the toast for non-validation errors:
+
+```ts
+import { useResourceMutation } from '@spree/dashboard-core'
+
+export function useUpdateBrand(id: string) {
+  return useResourceMutation({
+    mutationFn: (body: Partial<AdminBrand>) =>
+      adminClient.request<{ data: AdminBrand }>('PATCH', `/brands/${id}`, { body }),
+    invalidate: [['brands'], ['brand', id]],
+  })
+}
+```
+
+The `invalidate` array refetches dependent queries on success.
+
+## Error handling
+
+The SDK throws `SpreeError` for non-2xx responses. The error carries `status`, `code`, and `details` — the last contains the Rails error hash for 422s.
+
+```ts
+import { SpreeError } from '@spree/admin-sdk'
+
+try {
+  await adminClient.products.update(id, payload)
+} catch (err) {
+  if (err instanceof SpreeError && err.status === 422) {
+    console.log(err.details) // { name: ["can't be blank"] }
+  }
+  throw err
+}
+```
+
+In a React Hook Form submit handler, prefer the higher-level helper:
+
+```tsx
+import { mapSpreeErrorsToForm } from '@spree/dashboard-core'
+
+async function handleSubmit(values: FormValues) {
+  try {
+    await mutation.mutateAsync(values)
+  } catch (err) {
+    if (!mapSpreeErrorsToForm(err, form.setError)) throw err
+  }
+}
+```
+
+`mapSpreeErrorsToForm` routes flat field errors onto `aria-invalid` `<FieldError>` blocks and `:base` errors onto `errors.root.message` for a destructive banner. Returns `true` if it handled the error; otherwise re-throw so the global toast catches it.
+
+## When to add a new endpoint
+
+Pretty much always, for anything non-trivial. If you're filtering, sorting, or aggregating across multiple resources, do it on the backend — the API can join, scope, and serialize correctly in one round-trip, whereas the dashboard would have to fan out N requests and stitch them together. See the backend customization docs for adding controllers, serializers, and authorization.
+
+## Reference
+
+- [Admin API reference](../../../api-reference/admin-api/introduction.md) — 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)
+- [`mapSpreeErrorsToForm`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/form-errors.ts)

package/dist/developer/dashboard/customization/navigation.md

@@ -0,0 +1,211 @@
+---
+title: Navigation
+sidebarTitle: Navigation
+description: Add, modify, and remove items from the dashboard's main sidebar and settings sub-nav.
+---
+
+The dashboard has two navigation registries: **main sidebar** (`nav`) and **settings sub-shell** (`settingsNav`). Both are module singletons exposed from `@spree/dashboard-core` and consumed by `<AppSidebar>` and `<SettingsSidebar>` via `useSyncExternalStore`, so late registration re-renders the sidebars automatically.
+
+## Main sidebar (`nav`)
+
+### Add an entry
+
+```ts
+import { nav } from '@spree/dashboard-core'
+import { BarChartIcon } from 'lucide-react'
+
+nav.add({
+  key: 'analytics',
+  label: 'Analytics',
+  path: '/analytics',      // prefixed with /$storeId at render time
+  icon: BarChartIcon,
+  position: 650,
+  subject: 'Spree::Order', // optional CanCanCan subject — hides item without read permission
+})
+```
+
+`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.
+
+### Add via `defineDashboardPlugin`
+
+The facade groups multiple registry calls:
+
+```ts
+import { defineDashboardPlugin } from '@spree/dashboard-core'
+
+defineDashboardPlugin({
+  nav: [
+    { key: 'analytics', label: 'Analytics', path: '/analytics', icon: BarChartIcon, position: 650 },
+    { key: 'segments', label: 'Segments', path: '/segments', icon: UsersIcon, position: 660 },
+  ],
+})
+```
+
+### Nest children under a parent
+
+```ts
+nav.add({
+  key: 'analytics',
+  label: 'Analytics',
+  icon: BarChartIcon,
+  position: 650,
+  children: [
+    { key: 'analytics.sales', label: 'Sales', path: '/analytics/sales' },
+    { key: 'analytics.traffic', label: 'Traffic', path: '/analytics/traffic' },
+  ],
+})
+```
+
+Children declare their own `subject` independently — the parent doesn't auto-gate them.
+
+### Nest under an existing (built-in) parent
+
+To add an item **inside** a menu you don't own — e.g. a "Brands" page under the built-in **Products** menu — use `addChild`, which preserves the parent's existing children. (`nav.update('products', { children: [...] })` would *replace* them, dropping the built-ins.)
+
+```ts
+nav.addChild('products', {
+  key: 'products.brands',
+  label: 'Brands',
+  path: '/products/brands',
+  subject: 'Spree::Brand',
+})
+```
+
+Or declaratively, keyed by parent:
+
+```ts
+defineDashboardPlugin({
+  nav: {
+    addChildren: {
+      products: [{ key: 'products.brands', label: 'Brands', path: '/products/brands' }],
+    },
+  },
+})
+```
+
+Nesting under a missing parent throws; a duplicate child key throws (`updateChild` / `removeChild` mutate an existing one). Built-in parents (`products`, `orders`, `customers`, `promotions`) register during app bootstrap, before any plugin runs, so they're always available to nest into.
+
+### Insert relative to an existing entry
+
+```ts
+nav.insertBefore('customers', { key: 'segments', label: 'Segments', path: '/segments' })
+nav.insertAfter('orders', { key: 'returns', label: 'Returns', path: '/returns' })
+```
+
+The new entry inherits the target's `position` ± 1 unless you specify your own.
+
+### Modify or remove
+
+Imperatively:
+
+```ts
+nav.update('orders', { label: 'All orders' })
+nav.remove('legacy-thing')
+```
+
+Or declaratively in `defineDashboardPlugin` — the `nav` object form adds, removes, and patches in one config (built-in entries included; they register before any plugin runs):
+
+```ts
+defineDashboardPlugin({
+  nav: {
+    add: [{ key: 'reviews', label: 'Reviews', path: '/reviews', position: 650 }],
+    remove: ['promotions'],
+    update: { products: { label: 'Catalog', position: 150 } },
+  },
+})
+```
+
+The array form (`nav: [...]`) remains the shorthand for `{ add: [...] }`. The object form also takes `addChildren` (see [Nest under an existing parent](#nest-under-an-existing-built-in-parent)). `remove` of an unknown key is a no-op; `update` of an unknown key throws. `settingsNav` accepts the same object form (minus `addChildren` — settings entries are flat).
+
+### Bottom-pinned entries
+
+`section: 'bottom'` pins to the sidebar footer (where "Settings" lives by default):
+
+```ts
+nav.add({
+  key: 'help',
+  label: 'Help',
+  path: '/help',
+  icon: HelpCircleIcon,
+  section: 'bottom',
+})
+```
+
+### Conditional visibility and badges
+
+Beyond permission gating with `subject`, a top-level entry can hide itself based on app state (`if`) and render a component after its label (`badge`):
+
+```tsx
+nav.add({
+  key: 'onboarding',
+  label: 'Onboarding',
+  path: '/onboarding',
+  // Receives the current store/user/permissions; return false to hide.
+  if: ({ store }) => !storeFullyConfigured(store),
+  // A component, not an element — it can call hooks and return null.
+  badge: PendingTasksBadge,
+})
+```
+
+The built-in Getting Started entry works exactly this way: it shows a remaining-tasks count and disappears once every setup task is done. `if` combines with `subject` — both must pass.
+
+## Settings sub-nav (`settingsNav`)
+
+The settings page has its own sub-shell sidebar with grouped entries (Store, Localization, Team & Access, …). Entries cluster under groups defined separately.
+
+### Register a group
+
+```ts
+import { settingsNav } from '@spree/dashboard-core'
+
+settingsNav.addGroup({
+  key: 'integrations',
+  label: 'Integrations',
+  position: 500,
+})
+```
+
+### Add entries to a group
+
+```ts
+settingsNav.add({
+  key: 'stripe-tax',
+  label: 'Stripe Tax',
+  path: '/integrations/stripe-tax',  // prefixed with /$storeId/settings
+  group: 'integrations',
+  position: 100,
+  subject: 'Spree::TaxRate',
+})
+```
+
+### `comingSoon` badge
+
+Disabled entries with a "Soon" badge — useful for staging the rollout:
+
+```ts
+settingsNav.add({
+  key: 'reports',
+  label: 'Reports',
+  path: '/reports',
+  group: 'analytics',
+  comingSoon: true,
+})
+```
+
+## Permission gating
+
+`subject` on a nav entry checks `permissions.can('read', subject)` — when it fails, the sidebar item is hidden. **This is UX, not authorization.** The backend still enforces CanCanCan via `authorize!` on every API call. Hiding the link is a hint, not a security boundary.
+
+## Order of operations
+
+Nav registrations run at module-load time. The sidebar reads via `useSyncExternalStore`, so:
+
+- 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`, 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](translations.md).
+
+## Reference
+
+- [`NavEntry`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/nav-registry.ts) — the full shape including types for `children`, `position`, `subject`, `section`
+- [`SettingsNavEntry`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/settings-nav-registry.ts) — settings sub-nav types

package/dist/developer/dashboard/customization/permissions.md

@@ -0,0 +1,123 @@
+---
+title: Permissions
+sidebarTitle: Permissions
+description: How to hide UI behind CanCanCan permissions in your customisations — and why hiding is never the same as authorising.
+---
+
+The dashboard exposes the current admin's CanCanCan abilities to every component via the `usePermissions()` hook. The registry surfaces — nav entries, settings entries, custom routes — also accept a `subject` shortcut, and nav entries take a generic `if` predicate that reads from `permissions`.
+
+## Two layers
+
+UI gating is for **UX**. Backend authorization is for **security**. They are not the same:
+
+| Layer | Where | What it does |
+|---|---|---|
+| UI gating | Dashboard registries (`subject`, `if`) | Hides menu items, columns, buttons — keeps the interface tidy |
+| Authorization | Rails API controllers (CanCanCan, scopes) | Refuses the request when the user doesn't have permission |
+
+**Always rely on the backend for security.** Hiding a button is a hint to the user, not a wall. A user with browser dev tools (or the API token) can always hit the endpoint directly — your `authorize!` call is what stops them.
+
+## The `permissions` object
+
+```ts
+interface Permissions {
+  can(action: ActionName, subject: SubjectName): boolean
+  cannot(action: ActionName, subject: SubjectName): boolean
+  /** True when the matching rule has per-record conditions — expect possible 403s. */
+  isConditional(action: ActionName, subject: SubjectName): boolean
+}
+```
+
+It mirrors the backend ability at the **class level**:
+
+```ts
+permissions.can('read', 'Spree::Order')
+```
+
+Subjects are strings (`'Spree::Order'`, `'Spree::Product'`, or your own `'MyApp::Report'`). There is no client-side record-level check — when a rule is conditional on record attributes, `isConditional` returns `true` and the API is the arbiter: render the control and handle a possible 403.
+
+## `subject` shortcut
+
+Available on `NavEntry`, `SettingsNavEntry`, and `RouteEntry`. It hides the entry unless the user can `read` the subject:
+
+```ts
+nav.add({
+  key: 'reports',
+  label: 'Reports',
+  path: '/reports',
+  subject: 'Spree::Order',  // hides nav item without read:Spree::Order
+})
+```
+
+For routes, `subject` also renders a 403 page if the user navigates directly:
+
+```ts
+routes: [{
+  key: 'reports',
+  path: '/reports',
+  component: ReportsPage,
+  subject: 'Spree::Order',
+}],
+```
+
+Use `subject` whenever you want a "user can read this resource" check. For anything else, use `if`.
+
+## `if` predicate (nav entries)
+
+`if` on a nav entry is the escape hatch. It runs at render with `{ permissions, store, user }` and returns a boolean:
+
+```tsx
+import type { Store } from '@spree/admin-sdk'
+
+nav.add({
+  key: 'reports',
+  label: 'Reports',
+  path: '/reports',
+  if: ({ permissions, store }) =>
+    permissions.can('read', 'Spree::Order') &&
+    !!(store as Store | null)?.setup_tasks?.every((task) => task.done),
+})
+```
+
+(The `if` context types `store` loosely — cast to the SDK's `Store` for typed access, the same way the built-in Getting Started entry does.)
+
+Use it for combined checks (permission + store state), feature flags, multi-action checks (`can(update) && can(read)`), or anything the `subject` shortcut can't express in one string. It combines with `subject` — both must pass. (Slot entries have an `if` too, but it receives only the slot's own context — see [Slots](slots.md).)
+
+## Inside components
+
+Use the `usePermissions()` hook — it returns `{ permissions, rules, isLoading }`:
+
+```tsx
+import { usePermissions } from '@spree/dashboard-core'
+
+function ReportsPage() {
+  const { permissions } = usePermissions()
+  if (!permissions.can('read', 'Spree::Order')) {
+    return <Forbidden />
+  }
+  return <ReportsList />
+}
+```
+
+The same `permissions` object backs the nav registry's `if` predicate, so you can move logic between the two without changing behaviour. For declarative gating, `<Can I="update" a="Spree::Order">…</Can>` (also from `@spree/dashboard-core`) renders children only when the check passes.
+
+## Custom abilities
+
+If your customization introduces a new model on the backend, extend the CanCanCan ability there (typically a decorator on `Spree::PermissionSets::DefaultCustomer` or `Spree::PermissionSets::DashboardManagement`):
+
+```ruby
+# config/initializers/spree.rb (host app)
+Spree::PermissionSets::DashboardManagement.class_eval do
+  def activate!
+    super
+    can :manage, MyApp::Report
+  end
+end
+```
+
+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/providers/permission-provider.tsx)
+- [CanCanCan docs](https://github.com/CanCanCommunity/cancancan) — the Ruby ability definition language

package/dist/developer/dashboard/customization/quickstart.md

@@ -0,0 +1,100 @@
+---
+title: Quickstart
+sidebarTitle: Quickstart
+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 two things are running:
+
+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/`; add it to an existing project with `npx spree add dashboard`, or scaffold it anywhere with `npx spree add dashboard --template` pointing at your own copy. Start it with `pnpm dev`.
+
+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](../plugins/overview.md).
+
+## The 30-second example
+
+Add an "Analytics" item to the dashboard sidebar.
+
+**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'
+import { BarChartIcon } from 'lucide-react'
+
+defineDashboardPlugin({
+  nav: [{
+    key: 'analytics',
+    label: 'Analytics',
+    path: '/analytics',
+    icon: BarChartIcon,
+    // Built-in entries use positions 100–600 (Home … Reports).
+    // 650 places Analytics after Reports, at the end.
+    position: 650,
+  }],
+})
+```
+
+**Step 2.** Save. The dev server hot-reloads and the sidebar now shows "Analytics".
+
+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 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 AnalyticsPage() {
+  return (
+    <ResourceLayout
+      header={<PageHeader title="Analytics" subtitle="Store performance over time" />}
+      main={<p>Coming soon.</p>}
+    />
+  )
+}
+```
+
+**Step 4.** Register the route in `src/plugins.ts`:
+
+```tsx
+import { defineDashboardPlugin } from '@spree/dashboard-core'
+import { BarChartIcon } from 'lucide-react'
+import { AnalyticsPage } from './pages/analytics'
+
+defineDashboardPlugin({
+  nav: [{
+    key: 'analytics',
+    label: 'Analytics',
+    path: '/analytics',
+    icon: BarChartIcon,
+    position: 650,
+  }],
+  routes: [{
+    key: 'analytics',
+    path: '/analytics',
+    component: AnalyticsPage,
+  }],
+})
+```
+
+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.
+
+## What just happened
+
+`defineDashboardPlugin` registers extensions against the dashboard's shared registries: `nav`, `routes`, `slots`, `tables`, `settingsNav`, `formFields`, and `customFieldComponents`. 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 `/<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](routes.md) 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](navigation.md) — sidebar entries, nesting under built-in menus, settings sub-nav, permission gating
+- [Routes](routes.md) — path patterns, params, permission fallback
+- [Slots](slots.md) — inject widgets into built-in pages without forking them
+- [Tables](tables.md) — define your own list page or extend built-in tables
+- [Translations](translations.md) — add i18n keys without colliding with the framework