@spree/docs 0.1.122 → 0.1.124

package/dist/developer/dashboard/deployment.md

@@ -0,0 +1,80 @@
+---
+title: Deploying the dashboard
+sidebarTitle: Deployment
+description: Ship the React Dashboard to production — served by the Spree server itself (the default), or as a static build on a CDN.
+---
+
+The dashboard deploys as **static files**. `vite build` produces `dist/` — HTML, JS, CSS — there is no Node server in production. What varies is who serves those files.
+
+> **WARNING:** `VITE_`-prefixed values are compiled into the client bundle — never put credentials in them. The dashboard authenticates admins interactively (JWT in memory + an httpOnly refresh cookie); no API keys are involved.
+
+## Single node — the default
+
+The Spree server serves the dashboard itself at **`/dashboard`**: one container, one origin, zero CORS or cookie configuration. The official Spree Docker image ships with the stock dashboard baked in — deploy the image anywhere Docker runs (Render, Railway, AWS, Azure, your own host) and `https://your-api-host/dashboard` just works.
+
+Under the hood, the **`spree_dashboard` gem** (in the Gemfile of the starter and the official image) serves the directory in `Spree::Dashboard.dist_path` — or the `SPREE_DASHBOARD_DIST_PATH` env var — with SPA semantics: every dashboard route falls back to `index.html`, hashed assets get immutable caching. The bundle is built with a **relative API base** (`VITE_SPREE_API_URL` unset) and `base: /dashboard/`, so the same image works on every host and environment with no rebuild. API-only deployments simply omit the gem.
+
+### Custom dashboard, single node
+
+The official image contains the *stock* dashboard. Once you've customized yours (your own pages/plugins in `apps/dashboard/`), bake your build into your own image:
+
+```bash
+spree build --production            # optionally --tag registry/repo:tag
+```
+
+The command detects `apps/dashboard/`, selects the Dockerfile's `custom` dashboard stage (`--build-arg DASHBOARD_SOURCE=custom`), and passes your app as a named build context — the Node toolchain lives only in that throw-away stage, and the final image is Rails plus your built `dist/` served at `/dashboard`. Without the CLI, the equivalent is:
+
+```bash
+docker build backend/ -f backend/Dockerfile \
+  --build-arg DASHBOARD_SOURCE=custom \
+  --build-context dashboard-src=./apps/dashboard \
+  -t my-shop-spree:latest
+```
+
+Inside the stage the build runs with `VITE_BASE_PATH=/dashboard/` (asset URLs resolve under the mount) and `VITE_SPREE_API_URL` unset (API calls stay origin-relative). Projects **without** `apps/dashboard/` build exactly what plain `docker build backend/` produces — and if your `backend/Dockerfile` predates dashboard support, the command warns instead of silently shipping the stock dashboard over your customized one.
+
+## Static host / CDN — the alternative
+
+For edge-served assets or an independent dashboard release cadence, deploy `dist/` to a static host on its own domain:
+
+```bash
+cd apps/dashboard
+VITE_SPREE_API_URL=https://api.mystore.com pnpm build
+```
+
+This is the **cross-origin** topology, with three requirements:
+
+1. **HTTPS on both sides.** The refresh cookie is issued with `SameSite=None; Secure` in production, and browsers drop `Secure` cookies over HTTP. There is no insecure-production mode.
+2. **Allowed Origins.** Add the dashboard's URL (e.g. `https://dashboard.mystore.com`) to **Settings → Allowed Origins** in the Spree admin — the API rejects cross-origin requests until then.
+3. **SPA fallback.** Every path must rewrite to `index.html` so the router owns the URL (`/* → /index.html` on your host: `_redirects` on Netlify, `vercel.json` rewrites, `try_files $uri /index.html;` on nginx).
+
+A middle ground also works: serve `dist/` and proxy `/api/*` + `/rails/*` to Rails from one domain behind your own nginx/Caddy/ingress — same-origin simplicity without baking the bundle into the image.
+
+## Render
+
+If your project deploys to Render via the Blueprint that `create-spree-app` places at the project root, `spree add dashboard` wires the single-node topology automatically: it extends the backend service's `buildCommand` to also build `apps/dashboard` (Render's Ruby runtime includes Node, and the full repo is available during the build) and adds one env var so the server serves the result:
+
+```yaml
+buildCommand: bundle install && … && (cd ../apps/dashboard && corepack enable pnpm && pnpm install && VITE_BASE_PATH=/dashboard/ pnpm build)
+envVars:
+  - key: SPREE_DASHBOARD_DIST_PATH
+    value: ../apps/dashboard/dist
+```
+
+That's the whole setup — one service, one origin, **your customized dashboard** (it builds from your `apps/dashboard`, not the stock bundle) at `https://your-service.onrender.com/dashboard`. No `VITE_SPREE_API_URL`, no Allowed Origins entry, no extra service. Redeploys rebuild on every push.
+
+If you prefer the dashboard on Render's CDN instead, add a static-site service by hand using the cross-origin recipe above.
+
+## Any other static host
+
+The same three ingredients, by hand: build with `VITE_SPREE_API_URL` set, upload `dist/`, configure the `/* → /index.html` rewrite. Then add the origin to Allowed Origins.
+
+## Checklist (cross-origin only)
+
+Single-node deployments skip all of this — one origin needs none of it.
+
+- [ ] `VITE_SPREE_API_URL` points at the production API (baked at build time — one build per environment)
+- [ ] HTTPS on the dashboard *and* the API
+- [ ] Dashboard origin added to **Settings → Allowed Origins**
+- [ ] All paths rewrite to `index.html`
+- [ ] No secrets in any `VITE_` variable

package/dist/developer/dashboard/overview.md

@@ -0,0 +1,105 @@
+---
+title: React Dashboard Overview
+sidebarTitle: Overview
+description: Learn about the Spree React Dashboard architecture and how to customize it and extend it
+---
+
+> **INFO:** The React Dashboard is currently a **Developer Preview** — APIs may still change between releases. 
+> In Spree 6 it will become the default Admin interface replacing the Spree 5 admin.
+
+The React Dashboard is a React single-page application (SPA) that talks to the [Spree Admin API](../../api-reference/admin-api.md). 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 |
+|---|---|
+| Build & dev | [Vite](https://vitejs.dev/) |
+| Routing | [TanStack Router](https://tanstack.com/router) (file-based, type-safe) |
+| Data fetching | [TanStack Query](https://tanstack.com/query) |
+| Forms | [React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/) |
+| UI primitives | [shadcn/ui](https://ui.shadcn.com/) + [Base UI](https://base-ui.com/) + [Tailwind CSS](https://tailwindcss.com/) |
+| Icons | [lucide-react](https://lucide.dev/) |
+| Charts | [Recharts](https://recharts.org/) |
+| Rich text | [Tiptap](https://tiptap.dev/) |
+| Notifications | [Sonner](https://sonner.emilkowal.ski/) |
+| Lint & format | [Biome](https://biomejs.dev/) |
+
+### Packages
+
+Dashboard consinsts of 3 NPM packages, each with a different purpose. You can import any of them in your host app or plugin package.
+
+| Package | What it contains | When you touch it |
+|---|---|---|
+| `@spree/dashboard-ui` | Design system: [shadcn](https://ui.shadcn.com/) primitives + headless composed components (`PageHeader`, `ResourceLayout`, `ResourceTable`'s rendering layer, etc.) + design tokens | Building custom UI — primitives + compounds you can drop anywhere |
+| `@spree/dashboard-core` | Framework: registries (nav, route, slot, table, settings-nav), providers (auth, permission, store), admin SDK client, infra hooks, the `defineDashboardPlugin` API | Extending the admin — every customization API lives here |
+| `@spree/dashboard` | The deployable SPA: routes, resource hooks, schemas, locale strings, app shell | Replacing or restyling specific routes (rare) |
+
+Most customization happens via `@spree/dashboard-core`. You import its registries from your own host-app code (or from a separate plugin package) to add nav entries, routes, slot widgets, table columns, and translations.
+
+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.
+
+## Get the dashboard
+
+Your copy of the dashboard is a small Vite app (the "host app") that imports `<Dashboard />` from `@spree/dashboard` — you own its `package.json`, Vite config, and a `src/plugins.ts` for customizations. Two ways to get one:
+
+- **New project:** `npx create-spree-app my-store` — answer **Yes** to "Include React Dashboard?" and it lands in `apps/dashboard/`, pointed at your API.
+- **Existing project:** run `npx spree add dashboard` from your project root — same result.
+
+Either way: `cd apps/dashboard && npm run dev`, open http://localhost:5173, and sign in with your admin email and password. No API keys to configure — admins authenticate interactively.
+
+## Choose your path
+
+There are two ways to customize the dashboard. **Both use the same APIs** — the only difference is packaging.
+
+### 1. Customize in your host app (Recommended)
+
+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
+// 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', position: 650 }],
+  routes: [{ key: 'analytics', path: '/analytics', component: MyAnalyticsPage }],
+})
+```
+
+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**](customization/quickstart.md).
+
+### 2. Ship a redistributable plugin
+
+You're building a feature that multiple Spree stores will install — a Brands gem, a Wishlists integration, a Stripe Tax connector. Package the customization as an npm module so any host app can install it with a single `pnpm add my-plugin`.
+
+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](plugins/publishing.md))
+- **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](plugins/distributing.md) 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](customization/routes.md). (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:
+
+```bash
+npx @spree/cli plugin new my-feature
+```
+
+→ Start at the [**plugin scaffolding guide**](plugins/scaffolding.md).
+
+## Which one should I pick?
+
+Use this rule of thumb:
+
+- **Customize in-app** if the feature is store-specific (your branding, your team's workflow, your custom domain logic) or you don't yet know whether others would want it. The cost to "promote" it to a plugin later is small.
+- **Ship a plugin** if you're certain others will install it (you're publishing to the marketplace, your agency is rolling it out across clients, the feature has a clear standalone identity).
+
+When in doubt, customize in-app first. The migration path to a plugin is mechanical — same APIs, just wrapped in their own package.
+
+## Reference
+
+- [Customization quickstart](customization/quickstart.md)
+- [Plugin scaffolding](plugins/scaffolding.md)
+- [Slots catalog](slots-catalog.md) — every named slot the dashboard exposes
+- [`@spree/dashboard-core` README](https://github.com/spree/spree/tree/main/packages/dashboard-core) — full extension API reference
+- [Classic Admin extension model](../admin/extending-ui.md) — for Spree 5.x

package/dist/developer/dashboard/plugins/distributing.md

@@ -0,0 +1,137 @@
+---
+title: Distributing
+sidebarTitle: Distributing
+description: What consumers do to install your plugin — the wiring on the host side, what to document, and how to keep upgrades painless.
+---
+
+This page is the *consumer's* perspective on installing your plugin. Cover it in your README so users have a one-page reference.
+
+## The two steps
+
+A consumer installing your plugin needs to:
+
+1. **Install the npm package** — `pnpm add @your-scope/your-plugin`, then restart the dev server
+2. **Apply any backend changes** — usually adding a Rails gem, running migrations
+
+```bash
+pnpm add @your-scope/your-plugin
+
+# Rails side, if your plugin has a backend
+bundle add your_plugin
+bin/rails generate your_plugin:install
+bin/rails db:migrate
+```
+
+**No host-code edit.** As long as your plugin's `package.json` declares the `spree.dashboard.plugin` marker (the CLI scaffold does this for you — see [Publishing](publishing.md#tell-the-vite-plugin-where-to-find-you)), `spreeDashboardPlugin()` walks the host's dependencies at build time and finds it automatically. Discovery feeds two things:
+
+- **Activation** — the app entry imports `virtual:spree-dashboard-plugins` (the dashboard app shell and the starter template already do), a module the Vite plugin synthesizes with one side-effect import per discovered plugin. Your `defineDashboardPlugin` call runs before first render without the host touching `main.tsx`.
+- **Tailwind scanning** — your plugin's class names compile without any extra wiring.
+
+Installing a package activating its code in the admin is the same trust model as adding a gem to a Rails `Gemfile` — vet your dependencies. Hosts that want explicit control use the whitelist below.
+
+Plugins that take configuration (the `definePlugin(config)` factory pattern — see below) are the exception: the factory call is host code, so the host imports and invokes it in `main.tsx` themselves.
+
+### Manual whitelist (advanced)
+
+For tightly controlled environments (a host that wants explicit allowlist semantics, or a plugin you want to load conditionally), pass the names explicitly:
+
+```ts
+// vite.config.ts (your dashboard app)
+spreeDashboardPlugin({
+  plugins: ['@your-scope/your-plugin'],  // disables auto-discovery
+})
+```
+
+Passing `plugins: []` disables auto-discovery entirely — useful if you want to ship a vanilla dashboard with zero third-party Tailwind sources.
+
+## Dev-mode banner
+
+If the consumer registers your plugin explicitly but it's not installed (or the spelling is off), `@spree/dashboard-core/vite` shows a Vite error overlay during dev with the package name and a fix-it checklist. The same overlay fires if a discovered plugin can't be resolved on disk. That replaces the older silent-failure mode where missing plugins emitted unstyled HTML.
+
+## What to put in your README
+
+A README that gets users to "working in five minutes" has:
+
+- A one-paragraph "what this does"
+- Screenshots or a short clip of the dashboard UI it adds
+- The four install steps (literally copy-paste blocks)
+- A "configuration" section if the plugin has runtime config
+- A "compatibility" table (`@spree/dashboard >=6.0.0`, `Spree >=6.0.0`, etc.)
+- Links to the source for slots/components the plugin overrides
+
+Skip the "philosophy" and the "alternative approaches" sections. Get users to working in minutes.
+
+## Configuration patterns
+
+Plugins occasionally need runtime config — API endpoints, feature toggles, custom permissions. Two patterns:
+
+### Module-level `configure` call
+
+```ts
+// in your plugin
+let _config = { endpoint: '/default' }
+export function configure(opts: { endpoint?: string }) {
+  _config = { ..._config, ...opts }
+}
+export function getConfig() { return _config }
+```
+
+```ts
+// consumer
+import { configure } from '@your-scope/your-plugin'
+configure({ endpoint: '/custom' })
+```
+
+Simple, no dependencies — but mind the timing: ES module imports are hoisted, so the plugin module (including any top-level `defineDashboardPlugin` call) always executes **before** your `configure(...)` line runs. This pattern therefore only works for values the plugin reads lazily — at render or fetch time, like an API endpoint — never for anything its import-time registration depends on. If config shapes what gets registered (which nav entries, which routes), use the factory pattern below instead.
+
+### `definePlugin(config)` factory
+
+```ts
+// in your plugin
+export function definePlugin(config: PluginConfig) {
+  // call defineDashboardPlugin inside, closing over config
+}
+```
+
+```ts
+// consumer
+import { definePlugin } from '@your-scope/your-plugin'
+definePlugin({ endpoint: '/custom' })
+```
+
+A bit more boilerplate but easier to test, and the order is unambiguous — no side-effect-at-import-time. If you go this route, drop the auto-registering entry-point and document `definePlugin` as *the* way to install.
+
+## Upgrades
+
+When you cut a major version of your plugin, the breaking-changes section of your changelog needs to call out:
+
+- Renamed registry keys (`nav.add({ key: ... })` changes are user-visible — their URLs depend on it)
+- Locale-key renames (consumers may have overrides keyed off old names)
+- Slot ID changes (consumers extending your slots break)
+- `peerDependencies` range bumps (consumers may need to upgrade Spree first)
+
+Treat the plugin's public surface as: nav keys, route paths, slot IDs, locale keys, and the exported `configure` / `definePlugin` API. Everything else is internal.
+
+## Coexistence with other plugins
+
+The registries are global singletons, so a key collision is the consumer's problem to debug. Mitigations:
+
+- **Namespace your keys** — `key: 'acme-brands'` not `key: 'brands'`.
+- **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.
+
+## Distribution channels
+
+- **npm public** — what most plugins want. `pnpm publish --access public`.
+- **npm private (paid)** — for commercial plugins; combine with a license key checked at runtime.
+- **GitHub Package Registry** — internal-only; consumers add `@your-scope:registry=https://npm.pkg.github.com` to `.npmrc`.
+- **Git tarball** — `pnpm add github:your-org/your-plugin#main` works for unpublished plugins, useful while iterating against a single consumer.
+
+For pre-1.0 plugins, ship under the `next` dist-tag (`pnpm publish --tag next`) so `pnpm add @your-scope/your-plugin` resolves to the stable line and `pnpm add @your-scope/your-plugin@next` opts in.
+
+## Reference
+
+- [Example consumer wiring](https://github.com/spree/spree/blob/main/packages/dashboard/vite.config.ts) — what `spreeDashboardPlugin` looks like in production
+- [Plugins reference (`brands` example)](https://github.com/spree/spree/tree/main/packages/dashboard-plugin-example) — what a finished plugin looks like end-to-end

package/dist/developer/dashboard/plugins/overview.md

@@ -0,0 +1,46 @@
+---
+title: Plugin overview
+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 `src/plugins.ts` in your dashboard app and skip this section entirely — start with the [Customization](../customization/quickstart.md) 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.
+
+## What "plugin" means here
+
+A dashboard plugin is:
+
+1. **An npm package** — published, versioned, installed via `pnpm add @your-scope/your-plugin`.
+2. **One side-effecting entry-point** — `import '@your-scope/your-plugin'` calls `defineDashboardPlugin({ ... })` at module-load time, which registers nav entries, routes, slots, columns, etc.
+3. **Auto-discovered** — the `"spree": { "dashboard": { "plugin": true } }` marker in your package.json is all the host needs; `spreeDashboardPlugin()` finds every installed dependency carrying it, activates the entry-point, and scans your source for Tailwind classes so you never ship pre-built CSS. (Hosts can pass an explicit `plugins: [...]` array to opt out of discovery and whitelist instead.)
+4. **Translations-aware** — your bundle ships JSON locale files and calls `i18n.addResourceBundle('en', 'translation', bundle, true, true)` on import (keys nested under a top-level `admin` object).
+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 `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
+
+| Scenario | Approach |
+|---|---|
+| Single project, your own team | In-app customization |
+| Two-three internal projects sharing the same extension | Internal npm package (still a plugin) |
+| Open-source integration distributed via npm | Plugin |
+| 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 `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
+
+- [Scaffolding](scaffolding.md) — `spree plugin new <name>` generates the monorepo
+- [Publishing](publishing.md) — package metadata, semver, the npm bits
+- [Distributing](distributing.md) — what consumers do to install it
+
+If you haven't yet, read the [Customization](../customization/quickstart.md) section first. It's where the registry API is documented; the plugin pages mostly cover *packaging* concerns.
+
+## Reference
+
+- [Reference: Plugin example (`brands` repo)](https://github.com/spree/spree/tree/main/packages/dashboard-plugin-example) — vendored reference implementation
+- [`defineDashboardPlugin` source](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/plugin.ts)

package/dist/developer/dashboard/plugins/publishing.md

@@ -0,0 +1,142 @@
+---
+title: Publishing
+sidebarTitle: Publishing
+description: Get a dashboard plugin onto npm — package metadata, peer dependencies, TypeScript builds, versioning with Changesets.
+---
+
+`@spree/cli plugin new` scaffolds the npm package shape, but you still need to fill in publishing-specific metadata before `pnpm publish`. This page covers what to set and why.
+
+## Set the right `peerDependencies`
+
+Your plugin imports React, the dashboard, Tailwind, i18next, etc., but **you don't bundle them** — the host app has those, and bundling them twice causes either duplicate module instances or a tree-shaken nightmare. Use `peerDependencies`:
+
+```json
+{
+  "peerDependencies": {
+    "react": "^19",
+    "react-dom": "^19",
+    "@spree/dashboard-core": "^0.1.0",
+    "@spree/dashboard-ui": "^0.1.0",
+    "@spree/admin-sdk": "^0.5.0",
+    "i18next": "^26",
+    "react-i18next": "^17",
+    "@tanstack/react-query": "^5",
+    "@tanstack/react-router": "^1",
+    "lucide-react": "^1"
+  }
+}
+```
+
+Use ranges, not exact versions — pin too tightly and consumers can't upgrade the dashboard without you cutting a release. One Developer Preview caveat: for `0.x` versions, `^` only allows patch-level drift (`^0.1.0` matches `0.1.x`, not `0.2.0`), so expect to bump your `@spree/dashboard-*` peers alongside dashboard releases until 1.0. `spree plugin new` scaffolds these ranges for you, matched to the current release.
+
+`dependencies` is for things your plugin *uses* that the host *doesn't* — small utilities (e.g., `clsx`, `date-fns` if you need a specific version, your own helper packages). When in doubt, peer-dep it. The trade-off is "user has to install one more thing" vs. "user has two copies of React" — always pay the first cost.
+
+## Choose what to publish
+
+The scaffold's `package.json` ships TS source by default. Two options:
+
+### Option A — Ship pre-built JS
+
+Run `tsup` on publish, ship `dist/`:
+
+```json
+{
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "src/locales"],
+  "scripts": {
+    "build": "tsup src/index.tsx --format cjs,esm --dts --external react",
+    "prepublishOnly": "pnpm build"
+  }
+}
+```
+
+Pre-built JS is friendlier to consumers using non-Vite bundlers and means your code runs regardless of the host's TS config.
+
+### Option B — Ship source
+
+```json
+{
+  "main": "./src/index.tsx",
+  "types": "./src/index.tsx",
+  "files": ["src"]
+}
+```
+
+Vite + tsup can consume TSX directly. Simpler builds, hot reload across the boundary in dev, but only works for Vite-host consumers. Spree dashboards always use Vite, so this is safe in practice.
+
+Pick A if you're going to npm in earnest. Pick B for internal-only packages used inside a known-Vite setup.
+
+## Side-effects flag
+
+The plugin's whole purpose is side effects (`defineDashboardPlugin` registers stuff at module-load time). **Tell bundlers not to tree-shake it:**
+
+```json
+{
+  "sideEffects": ["./src/index.tsx", "./dist/index.js", "./dist/index.cjs"]
+}
+```
+
+Without this, a bundler can decide that `import '@your-scope/your-plugin'` does nothing useful and drop it. The list is what's allowed to have effects; everything else still tree-shakes.
+
+## Tell the Vite plugin where to find you
+
+Declare your package as a dashboard plugin in its own `package.json`:
+
+```json
+{
+  "spree": {
+    "dashboard": {
+      "plugin": true,
+      "routes": "./src/routes"
+    }
+  }
+}
+```
+
+`routes` (optional) points at your TanStack file-routes directory; the host build compiles it into its typed route tree — see the [routes guide](../customization/routes.md).
+
+This marker is what powers **auto-discovery**: when a host calls `spreeDashboardPlugin()` without an explicit `plugins` array (the default), the Vite plugin walks the host's `package.json` deps + devDeps, reads each one's manifest, and picks up anything with `spree.dashboard.plugin: true`. The host doesn't have to know your plugin's name — `pnpm add @your-scope/your-plugin` is the entire installation step.
+
+The CLI scaffold (`spree plugin new`) writes this field for you. If you're hand-rolling a plugin, add it before publishing — without it, hosts that rely on auto-discovery won't find your plugin and Tailwind won't pick up your class names.
+
+## Export the Tailwind source
+
+`spreeDashboardPlugin` uses `require.resolve(...)` to find your package, then walks `src/` for Tailwind class scanning. As long as you ship `src/`, it works — Tailwind picks up `className="..."` strings from your built code without you publishing CSS.
+
+If you only ship `dist/` and your built code mangles class names (Tailwind can't see `text-${variant}-500`), use static class names or expose a `tailwind.config.js` content array.
+
+## Versioning with Changesets
+
+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
+git commit -am "feat: x"
+pnpm changeset version   # bumps package versions + writes CHANGELOG
+pnpm install             # resolve workspace versions
+git commit -am "Release"
+pnpm publish -r          # publish updated packages
+```
+
+Standalone plugin repos can run Changesets the same way; the CLI scaffold doesn't pre-configure it.
+
+## Publishing the npm package
+
+```bash
+pnpm build
+pnpm publish --access public
+```
+
+Set `"private": false` and remove the `"publishConfig.access": "restricted"` if your scaffold has it.
+
+## Avoiding lock-step releases
+
+Your plugin should compile against a **range** of dashboard versions. Run the build against the lowest supported version locally (`pnpm add -D @spree/dashboard-core@6.0.0`) and add a CI matrix job that bumps to the next minor and rebuilds. That's the cheapest way to catch "I depended on something that doesn't exist in 6.0.0".
+
+## Reference
+
+- [npm `peerDependencies` docs](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#peerdependencies)
+- [Changesets](https://github.com/changesets/changesets)
+- [tsup docs](https://tsup.egoist.dev/)

package/dist/developer/dashboard/plugins/scaffolding.md

@@ -0,0 +1,133 @@
+---
+title: Scaffolding
+sidebarTitle: Scaffolding
+description: Generate a new dashboard plugin monorepo with `@spree/cli` in one command. Includes TypeScript, biome, tsup, a working example entry-point, and translations.
+---
+
+`@spree/cli` ships a `plugin new` command that scaffolds the whole plugin monorepo for you. Generated layout:
+
+```
+your-plugin/
+├── package.json            # workspace root
+├── pnpm-workspace.yaml
+├── LICENSE
+├── README.md
+├── .gitignore
+└── packages/
+    └── dashboard/
+        ├── package.json    # @your-scope/dashboard-your-plugin
+        ├── tsconfig.json
+        ├── biome.json
+        └── src/
+            ├── index.tsx   # defineDashboardPlugin entry
+            ├── client.ts   # adminClient request wrappers
+            ├── types.ts    # plugin-specific TS types
+            ├── pages/
+            │   └── <name>-list.tsx
+            ├── routes/     # TanStack file routes, compiled into the host's typed route tree
+            │   └── <name>.index.tsx
+            ├── slots/
+            │   └── product-<name>-card.tsx
+            └── locales/
+                └── en.json
+```
+
+You get a working "Brands"-style plugin out of the box: nav entry, a list page wired through React Query, a product-detail slot card, and English translations.
+
+## Run it
+
+```bash
+npx @spree/cli plugin new my-plugin
+```
+
+The CLI prompts for:
+
+- **Plugin name** — slug (kebab-case), used for package names and i18n keys
+- **Ruby gem name** — only matters if you later add a Rails engine
+- **Module name** — PascalCase, used as the React component prefix (`MyPluginCard`)
+- **npm scope** — e.g., `@acme`
+- **Author + email** — for `package.json` and `LICENSE`; prefilled from `git config user.name` / `user.email`
+- **License** — MIT, Apache-2.0, or BSD-3-Clause (MIT by default); the CLI fills in the standard text
+
+Every prompt has a matching flag:
+
+```bash
+npx @spree/cli plugin new my-plugin \
+  --ruby-name spree_my_plugin \
+  --module-name MyPlugin \
+  --npm-scope @acme \
+  --author "Ada Lovelace" \
+  --author-email "ada@example.com" \
+  --license MIT \
+  --no-install        # skip pnpm install
+```
+
+For CI and scripted use, `-y` / `--yes` accepts the default for anything the flags leave unanswered — author and email come from your git config, everything else derives from the plugin name:
+
+```bash
+npx @spree/cli plugin new my-plugin -y
+```
+
+`--force` overwrites an existing directory. `--no-dashboard` skips the dashboard package (Rails-engine-only plugins). `--no-engine` is reserved — engine scaffolding lands later.
+
+## After scaffolding
+
+```bash
+cd my-plugin
+pnpm install          # runs by default unless --no-install
+pnpm build
+```
+
+You now have a buildable plugin. The next page covers what to put in `package.json` for publishing — but if you're using it internally and importing by path, you can stop here and skip [Publishing](publishing.md).
+
+## What the entry-point looks like
+
+`packages/dashboard/src/index.tsx` is where everything starts. The generated version, trimmed:
+
+```tsx
+import { defineDashboardPlugin, defineTable, i18n } from '@spree/dashboard-core'
+import { PackageIcon } from 'lucide-react'
+
+import { MyPluginCard } from './slots/product-my-plugin-card'
+
+// 1. Translations — merge our keys into the shared bundle.
+i18n.addResourceBundle('en', 'translation', en, true, true)
+
+// 2. Declare the table our list page renders with <ResourceTable>.
+defineTable('my-plugin', {
+  title: i18n.t('admin.my_plugin.table.title'),
+  defaultSort: { field: 'name', direction: 'asc' },
+  columns: [/* … */],
+})
+
+// 3. Registry extensions. Routes are NOT registered here — they ship as
+// file routes in src/routes/ (declared via the package.json marker) and
+// compile into the host's typed route tree. See the routes guide.
+defineDashboardPlugin({
+  nav: [{
+    key: 'my-plugin',
+    label: i18n.t('admin.my_plugin.title'),
+    path: '/my-plugin',
+    icon: PackageIcon,
+    position: 250,
+  }],
+  slots: {
+    'product.form_sidebar': [{
+      id: 'my-plugin-card',
+      component: MyPluginCard as never,
+      position: 50,
+    }],
+  },
+})
+```
+
+That's the whole entry-point. Edit it to register what your plugin needs and remove what it doesn't.
+
+## The example endpoints
+
+The generated `client.ts` calls `adminClient.request()` against `/<name>` (relative to `/api/v3/admin`) — those endpoints don't exist by default. You'd add them on the Rails side (a controller, a model, a serializer) for the plugin to do anything end-to-end. The CLI doesn't scaffold the Rails engine today; for now, write that part by hand using the [backend integration docs](../customization/backend.md).
+
+## Reference
+
+- [`@spree/cli` source](https://github.com/spree/spree/tree/main/packages/cli)
+- [Template tree](https://github.com/spree/spree/tree/main/packages/cli/templates/plugin) — what gets copied (`.tt` files are template-substituted)