@spree/cli 3.0.1 → 3.1.0

package/dist/templates/dashboard-starter/AGENTS.md

@@ -0,0 +1,71 @@
+# Agent Instructions
+
+This is the Spree admin dashboard for this project — a Vite + React app. The
+shell (routes, chrome, resource pages) ships in `@spree/dashboard`; this
+project holds your customizations.
+
+Full docs: https://spreecommerce.org/docs/developer/dashboard/overview
+
+## Imports
+
+Import from `@spree/dashboard` — it re-exports the framework and the design
+system, so there is no need to work out which package an export lives in.
+
+```ts
+import { defineDashboardPlugin, useStore, Button, ResourceTable } from '@spree/dashboard'
+```
+
+`@spree/dashboard-core` and `@spree/dashboard-ui` stay importable for the few
+components that exist in both: the design system's takes data as props, the
+framework's fetches its own. The facade gives you the framework's.
+
+## Where code goes
+
+Organized by kind, one file per resource — the same layout `@spree/dashboard`
+uses internally.
+
+| Directory | Holds | Naming |
+|---|---|---|
+| `src/plugins.ts` | Registrations only: nav, routes, slots, tables | one file |
+| `src/pages/` | One screen each | `brands.tsx` |
+| `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 map
+of what exists, not an implementation.
+
+## Rules
+
+- **The Admin API is the only data source.** Never reach into the Rails app or
+  import server-rendered HTML. A missing endpoint is added to the API first.
+- **Wrap API calls in a hook.** Components never call `adminClient` directly.
+- **Query keys are store-scoped.** Build them with `useResourceKey`; a bare
+  `['brands']` key leaks one store's data into another after a store switch.
+- **Writes go through `useResourceMutation`**, which maps 422 responses onto
+  form fields instead of firing a toast.
+- **Every visible string goes through i18next** — page titles, column labels,
+  buttons, empty states, toasts. Never hardcode English in JSX or in a table
+  definition. Add each new key to every locale file the project ships.
+- **Schemas hold canonical values, never labels.** Build `{ value, label }`
+  pairs at render time so labels stay translatable.
+- **Never embed an SDK entity type in a form-values type.** React Hook Form
+  walks every nested key and the SDK's object graph overflows the TypeScript
+  compiler.
+- **A sortable or filterable column must be allowlisted for Ransack** on the
+  model, or the request fails at runtime.
+- **Destructive actions that fire straight from a click need a confirm** —
+  `useConfirm()` with `variant: 'destructive'`.
+
+## Checks
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm test        # unit tests (Vitest, Node environment)
+pnpm build
+```
+
+Test the logic between the UI and the API — query keys, payload mapping, permission predicates. Do not write tests that render a component to assert its markup; that tests React. Use `pnpm test:e2e` when a browser is genuinely needed.

package/dist/templates/dashboard-starter/README.md

@@ -12,7 +12,7 @@ cp .env.example .env.local   # optional — VITE_API_PROXY_TARGET if your API is
 pnpm dev                     # http://localhost:5173
 ```
 
-The dev server proxies `/api` to your Rails backend so the SPA stays same-origin — don't set `VITE_SPREE_API_URL` in dev (it switches the SDK to absolute cross-origin URLs, which breaks on CORS and the auth cookie).
+The dev server proxies `/api` to your server API so the SPA stays same-origin — don't set `VITE_SPREE_API_URL` in dev (it switches the SDK to absolute cross-origin URLs, which breaks on CORS and the auth cookie).
 
 Sign in with an admin account — authentication is interactive (JWT + refresh cookie). No API keys belong in `.env.local`: every `VITE_`-prefixed value is compiled into the client bundle.
 
@@ -29,8 +29,119 @@ That's the whole install. `spreeDashboardPlugin()` (see `vite.config.ts`) discov
 
 `src/plugins.ts` is yours — register nav entries, routes, slot widgets, and table columns with `defineDashboardPlugin` from `@spree/dashboard-core`. Same API the distributed plugins use; see the [customization quickstart](https://spreecommerce.org/docs/developer/dashboard/customization/quickstart).
 
+**Import everything from `@spree/dashboard`.** It re-exports the framework
+(registries, providers, hooks, the Admin API client) and the design system, so
+you never have to remember which package a given export lives in:
+
+```ts
+import { defineDashboardPlugin, useStore, Button, ResourceTable } from '@spree/dashboard'
+```
+
+`@spree/dashboard-core` and `@spree/dashboard-ui` remain installed and
+importable when you want them directly — a handful of components exist in
+both, where the design system's version takes its data as props and the
+framework's fetches its own. The facade gives you the framework's.
+
+Brands will not be your only customization, so this starter ships the same layout `@spree/dashboard` uses internally: organized by kind, one file per resource.
+
+```
+src/
+├── plugins.ts     registrations only — the map of what you added
+├── pages/         one file per screen        brands.tsx, brand-detail.tsx
+├── 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
+```
+
+Adding a resource touches one file in each directory, which is why the split
+is by kind rather than by feature — you always know where a thing lives.
+
+**`pages/`** — a screen composes `ResourceLayout` with a `PageHeader` and
+renders a `ResourceTable` or a form. It does not fetch data itself. Register
+it as a route in `plugins.ts`:
+
+```tsx
+import { BrandsPage } from './pages/brands'
+
+defineDashboardPlugin({
+  routes: [{ key: 'brands', path: '/brands', component: BrandsPage }],
+})
+```
+
+**`hooks/`** — named `use-<resource>.ts`, each wrapping the Admin API so
+components never call `adminClient` directly. Build query keys with
+`useResourceKey`, which scopes them to the current store; a bare `['brands']`
+key leaks one store's data into another after a store switch. Use
+`useResourceMutation` for writes — it maps 422 responses onto form fields
+instead of firing a toast.
+
+```ts
+import { adminClient, useResourceKey } from '@spree/dashboard-core'
+import { useQuery } from '@tanstack/react-query'
+
+export function useBrands() {
+  return useQuery({
+    queryKey: useResourceKey('brands'),
+    queryFn: () => adminClient.request('GET', '/brands'),
+  })
+}
+```
+
+**`tables/`** — one `defineTable` call per resource, at module load, imported
+from `plugins.ts` so it registers before the router mounts. Column changes to
+built-in tables (products, orders, customers) live here too. A column marked
+`sortable` or `filterable` must be allowlisted for Ransack on the model, or
+the request fails.
+
+**`schemas/`** — the Zod schema, its inferred `FormValues` type and defaults.
+Hold canonical values only, never label strings: build `{ value, label }`
+pairs at render time so labels stay translatable. Never embed an SDK entity
+type (`Product`, `Order`) in a form-values type — React Hook Form walks every
+nested 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 column
+labels and button text. Keys live under a top-level `admin` object. Load the
+bundle once at the top of `plugins.ts`:
+
+```ts
+import { i18n } from '@spree/dashboard-core'
+import en from './locales/en.json'
+
+i18n.addResourceBundle('en', 'translation', en, true, true)
+```
+
+## Test
+
+Vitest and Playwright are configured. Playwright needs its browser once:
+
+```bash
+pnpm exec playwright install chromium
+```
+
+```bash
+pnpm test        # unit tests: src/**/*.test.ts
+pnpm test:e2e    # end-to-end, through a browser
+```
+
+Unit tests run in Node rather than a DOM, because what is worth testing here is the logic between your UI and the API: query keys, payload mapping, permission predicates. Rendering a component to assert its markup tests React, not your feature — use an end-to-end test when you need a browser.
+
+`pnpm test:e2e` starts the dashboard itself and reuses one you already have running, but expects your API to be up (`spree dev`). Point it elsewhere with `E2E_BASE_URL`.
+
 ## Build & deploy
 
+The app root `Dockerfile` already builds this package and bakes it into the production image, available at `https://yourstore.com/dashboard` URL.
+
+If you want to host it elsewhere, eg. on CDN you can build it manually.
+
 ```bash
 pnpm build    # static assets in dist/
 ```

package/dist/templates/dashboard-starter/package.json

@@ -8,13 +8,18 @@
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --fix ."
   },
   "dependencies": {
-    "@spree/admin-sdk": "^1.0.0-beta.1",
-    "@spree/dashboard": "^1.0.0-beta.2",
+    "@spree/admin-sdk": "^1.0.0-beta.3",
+    "@spree/dashboard": "^1.0.0-beta.4",
+    "@spree/dashboard-core": "^1.0.0-beta.4",
+    "@spree/dashboard-ui": "^1.0.0-beta.4",
     "@tanstack/react-query": "^5.100.9",
     "@tanstack/react-router": "^1.169.2",
     "react": "^19.2.6",
@@ -22,11 +27,13 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
+    "@playwright/test": "^1.59.1",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "typescript": "~6.0.3",
-    "vite": "^8.0.16"
+    "vite": "^8.0.16",
+    "vitest": "^4.1.5"
   },
   "packageManager": "pnpm@11.13.1"
 }

package/dist/templates/dashboard-starter/playwright.config.ts

@@ -0,0 +1,37 @@
+import { defineConfig, devices } from '@playwright/test'
+
+// End-to-end tests run against your own stack: `spree dev` for the API, and
+// the dev server Playwright starts below. Point them somewhere else with
+// E2E_BASE_URL — a preview build, or a deployed environment.
+const BASE_URL = process.env.E2E_BASE_URL || 'http://localhost:5173'
+
+export default defineConfig({
+  testDir: './e2e',
+  // One worker: specs share a database, so parallel runs interfere unless
+  // every spec creates its own records under a unique name.
+  fullyParallel: false,
+  workers: 1,
+  retries: process.env.CI ? 2 : 0,
+  timeout: 30_000,
+  expect: { timeout: 10_000 },
+  reporter: process.env.CI ? [['github'], ['html', { open: 'never' }]] : 'list',
+
+  use: {
+    baseURL: BASE_URL,
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+
+  // Starts the dashboard for the run and reuses one you already have open.
+  // The API is expected to be running separately (`spree dev`).
+  webServer: process.env.E2E_BASE_URL
+    ? undefined
+    : {
+        command: 'pnpm dev --port 5173 --strictPort',
+        url: BASE_URL,
+        reuseExistingServer: true,
+        timeout: 60_000,
+      },
+})

package/dist/templates/dashboard-starter/src/locales/en.json

@@ -0,0 +1,3 @@
+{
+  "admin": {}
+}

package/dist/templates/dashboard-starter/src/plugins.ts

@@ -4,20 +4,30 @@
 // shared registries — the same API distributed plugins use. Imported once
 // from main.tsx, before the dashboard renders.
 //
+// Keep this file a map of what you added: the registrations live here, the
+// implementations live in pages/, hooks/, tables/ and schemas/. See the
+// README for what belongs where.
+//
 // Example:
 //
 //   import { defineDashboardPlugin } from '@spree/dashboard'
 //   import { AnalyticsPage } from './pages/analytics'
 //
 //   defineDashboardPlugin({
-//     nav: [{ key: 'analytics', label: 'Analytics', path: '/analytics', position: 60 }],
+//     nav: [{
+//       key: 'analytics',
+//       label: i18n.t('admin.analytics.nav'),
+//       path: '/analytics',
+//       position: 650,
+//     }],
 //     routes: [{ key: 'analytics', path: '/analytics', component: AnalyticsPage }],
 //   })
 //
-// Building custom pages? Add the framework and design-system packages first —
-// `pnpm add @spree/dashboard-core @spree/dashboard-ui` — then import hooks,
-// providers, and UI primitives from those.
-//
 // Docs: https://spreecommerce.org/docs/developer/dashboard/customization/quickstart
 
-export {}
+import { i18n } from '@spree/dashboard'
+import en from './locales/en.json'
+
+// Merges your `admin.*` keys into the dashboard's namespace without dropping
+// its own. Add a bundle per locale you ship.
+i18n.addResourceBundle('en', 'translation', en, true, true)

package/dist/templates/dashboard-starter/src/routeTree.gen.ts

@@ -52,6 +52,7 @@ import { Route as SettingsPayoutsRouteImport } from './../../dashboard/src/route
 import { Route as SettingsPaymentMethodsRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/settings/payment-methods'
 import { Route as SettingsPackageTypesRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/settings/package-types'
 import { Route as SettingsMarketsRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/settings/markets'
+import { Route as SettingsMarketplaceRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/settings/marketplace'
 import { Route as SettingsIntegrationsRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/settings/integrations'
 import { Route as SettingsEmailsRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/settings/emails'
 import { Route as SettingsCustomFieldDefinitionsRouteImport } from './../../dashboard/src/routes/_authenticated/$storeId/settings/custom-field-definitions'
@@ -324,6 +325,11 @@ const SettingsMarketsRoute = SettingsMarketsRouteImport.update({
   path: '/markets',
   getParentRoute: () => SettingsRoute,
 } as any)
+const SettingsMarketplaceRoute = SettingsMarketplaceRouteImport.update({
+  id: '/marketplace',
+  path: '/marketplace',
+  getParentRoute: () => SettingsRoute,
+} as any)
 const SettingsIntegrationsRoute = SettingsIntegrationsRouteImport.update({
   id: '/integrations',
   path: '/integrations',
@@ -659,6 +665,7 @@ export interface FileRoutesByFullPath {
   '/$storeId/settings/custom-field-definitions': typeof SettingsCustomFieldDefinitionsRoute
   '/$storeId/settings/emails': typeof SettingsEmailsRoute
   '/$storeId/settings/integrations': typeof SettingsIntegrationsRoute
+  '/$storeId/settings/marketplace': typeof SettingsMarketplaceRoute
   '/$storeId/settings/markets': typeof SettingsMarketsRoute
   '/$storeId/settings/package-types': typeof SettingsPackageTypesRoute
   '/$storeId/settings/payment-methods': typeof SettingsPaymentMethodsRoute
@@ -756,6 +763,7 @@ export interface FileRoutesByTo {
   '/$storeId/settings/custom-field-definitions': typeof SettingsCustomFieldDefinitionsRoute
   '/$storeId/settings/emails': typeof SettingsEmailsRoute
   '/$storeId/settings/integrations': typeof SettingsIntegrationsRoute
+  '/$storeId/settings/marketplace': typeof SettingsMarketplaceRoute
   '/$storeId/settings/markets': typeof SettingsMarketsRoute
   '/$storeId/settings/package-types': typeof SettingsPackageTypesRoute
   '/$storeId/settings/payment-methods': typeof SettingsPaymentMethodsRoute
@@ -857,6 +865,7 @@ export interface FileRoutesById {
   '/_authenticated/$storeId/settings/custom-field-definitions': typeof SettingsCustomFieldDefinitionsRoute
   '/_authenticated/$storeId/settings/emails': typeof SettingsEmailsRoute
   '/_authenticated/$storeId/settings/integrations': typeof SettingsIntegrationsRoute
+  '/_authenticated/$storeId/settings/marketplace': typeof SettingsMarketplaceRoute
   '/_authenticated/$storeId/settings/markets': typeof SettingsMarketsRoute
   '/_authenticated/$storeId/settings/package-types': typeof SettingsPackageTypesRoute
   '/_authenticated/$storeId/settings/payment-methods': typeof SettingsPaymentMethodsRoute
@@ -958,6 +967,7 @@ export interface FileRouteTypes {
     | '/$storeId/settings/custom-field-definitions'
     | '/$storeId/settings/emails'
     | '/$storeId/settings/integrations'
+    | '/$storeId/settings/marketplace'
     | '/$storeId/settings/markets'
     | '/$storeId/settings/package-types'
     | '/$storeId/settings/payment-methods'
@@ -1055,6 +1065,7 @@ export interface FileRouteTypes {
     | '/$storeId/settings/custom-field-definitions'
     | '/$storeId/settings/emails'
     | '/$storeId/settings/integrations'
+    | '/$storeId/settings/marketplace'
     | '/$storeId/settings/markets'
     | '/$storeId/settings/package-types'
     | '/$storeId/settings/payment-methods'
@@ -1155,6 +1166,7 @@ export interface FileRouteTypes {
     | '/_authenticated/$storeId/settings/custom-field-definitions'
     | '/_authenticated/$storeId/settings/emails'
     | '/_authenticated/$storeId/settings/integrations'
+    | '/_authenticated/$storeId/settings/marketplace'
     | '/_authenticated/$storeId/settings/markets'
     | '/_authenticated/$storeId/settings/package-types'
     | '/_authenticated/$storeId/settings/payment-methods'
@@ -1522,6 +1534,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof SettingsMarketsRouteImport
       parentRoute: typeof SettingsRoute
     }
+    '/_authenticated/$storeId/settings/marketplace': {
+      id: '/_authenticated/$storeId/settings/marketplace'
+      path: '/marketplace'
+      fullPath: '/$storeId/settings/marketplace'
+      preLoaderRoute: typeof SettingsMarketplaceRouteImport
+      parentRoute: typeof SettingsRoute
+    }
     '/_authenticated/$storeId/settings/integrations': {
       id: '/_authenticated/$storeId/settings/integrations'
       path: '/integrations'
@@ -1918,6 +1937,7 @@ interface SettingsRouteChildren {
   SettingsCustomFieldDefinitionsRoute: typeof SettingsCustomFieldDefinitionsRoute
   SettingsEmailsRoute: typeof SettingsEmailsRoute
   SettingsIntegrationsRoute: typeof SettingsIntegrationsRoute
+  SettingsMarketplaceRoute: typeof SettingsMarketplaceRoute
   SettingsMarketsRoute: typeof SettingsMarketsRoute
   SettingsPackageTypesRoute: typeof SettingsPackageTypesRoute
   SettingsPaymentMethodsRoute: typeof SettingsPaymentMethodsRoute
@@ -1950,6 +1970,7 @@ const SettingsRouteChildren: SettingsRouteChildren = {
   SettingsCustomFieldDefinitionsRoute: SettingsCustomFieldDefinitionsRoute,
   SettingsEmailsRoute: SettingsEmailsRoute,
   SettingsIntegrationsRoute: SettingsIntegrationsRoute,
+  SettingsMarketplaceRoute: SettingsMarketplaceRoute,
   SettingsMarketsRoute: SettingsMarketsRoute,
   SettingsPackageTypesRoute: SettingsPackageTypesRoute,
   SettingsPaymentMethodsRoute: SettingsPaymentMethodsRoute,

package/dist/templates/dashboard-starter/tsconfig.json

@@ -8,6 +8,7 @@
     "types": ["vite/client"],
     "skipLibCheck": true,
     "moduleResolution": "bundler",
+    "resolveJsonModule": true,
     "verbatimModuleSyntax": true,
     "moduleDetection": "force",
     "noEmit": true,

package/dist/templates/dashboard-starter/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    // Node, not jsdom: what is worth unit-testing here is the logic between
+    // your UI and the API — query keys, payload mapping, permission
+    // predicates. Rendering a component to assert its markup tests React.
+    // Reach for a browser through Playwright instead (`pnpm test:e2e`).
+    environment: 'node',
+    include: ['src/**/*.{test,spec}.{ts,tsx}'],
+    exclude: ['node_modules/**', 'e2e/**', 'dist/**'],
+  },
+})

package/dist/templates/plugin/README.md.tt

@@ -2,32 +2,25 @@
 
 A Spree plugin: **{{name}}**.
 
-This is a hybrid Node/Ruby monorepo with two halves:
+This monorepo holds the dashboard half of the plugin:
 
 - `packages/dashboard/` — TypeScript dashboard plugin (extends the Spree 6.0 admin via [`@spree/dashboard-core`](https://www.npmjs.com/package/@spree/dashboard-core))
-- `engine/` — Ruby Rails engine (Spree extension gem) that ships the Admin API endpoints and ActiveRecord models
 
-Both halves work together: the engine ships `/api/v3/admin/...` endpoints, the dashboard plugin calls them via the SDK's `request` method.
+The example pages call `/api/v3/admin/{{name}}` endpoints through the SDK's `request` method. Those endpoints don't exist yet — they belong in a Spree extension gem (a Rails engine) that you create separately, with its model, Admin API controller and permission scope, as described in [Creating an extension](https://spreecommerce.org/docs/developer/contributing/creating-an-extension). Then point your Spree host's Gemfile at it:
+
+```ruby
+gem '{{ruby_name}}', path: '../path/to/{{ruby_name}}'
+```
 
 ## Development setup
 
 ```bash
-# Install JavaScript dependencies
 pnpm install
-
-# Install Ruby dependencies for the engine
-cd engine && bundle install && cd ..
+pnpm build   # type-checks the plugin (it ships TypeScript source)
 ```
 
 ## Running against a Spree host app
 
-The engine needs to live alongside a Spree host (typically scaffolded via `create-spree-app`). Point your host's Gemfile at the local engine:
-
-```ruby
-# in your Spree host's Gemfile
-gem '{{ruby_name}}', path: '../path/to/{{plugin_name}}/engine'
-```
-
 Activate the dashboard plugin with a side-effect import in the host's `main.tsx`, before the router mounts. This runs `defineDashboardPlugin` so the nav entry, route, slot widget, and table column register:
 
 ```tsx
@@ -45,7 +38,7 @@ If you'd rather opt out of auto-discovery and register manually, pass an explici
 - [Plugin overview](https://spreecommerce.org/docs/developer/dashboard/plugins/overview) — packaging + publishing your plugin to npm
 - [Slots catalog](https://spreecommerce.org/docs/developer/dashboard/slots-catalog) — every named slot the dashboard exposes
 - [Custom Admin Endpoints](https://spreecommerce.org/docs/developer/sdk/admin/extending) — adding your own API endpoints
-- [Spree Extensions guide](https://spreecommerce.org/docs/developer/customization/extensions) — the Rails-engine side
+- [Creating an extension](https://spreecommerce.org/docs/developer/contributing/creating-an-extension) — the Rails-engine side
 
 ## License
 

package/dist/templates/plugin/packages/dashboard/package.json.tt

@@ -12,11 +12,15 @@
   "exports": {
     ".": "./src/index.tsx"
   },
+  "sideEffects": [
+    "./src/index.tsx"
+  ],
   "files": [
     "src",
     "README.md"
   ],
   "scripts": {
+    "build": "tsc --noEmit",
     "lint": "biome check src",
     "lint:fix": "biome check --fix src",
     "typecheck": "tsc --noEmit"
@@ -28,9 +32,9 @@
     }
   },
   "peerDependencies": {
-    "@spree/admin-sdk": "^0.6.0",
-    "@spree/dashboard-core": "^0.10.0",
-    "@spree/dashboard-ui": "^0.10.0",
+    "@spree/admin-sdk": "{{spree_admin_sdk_range}}",
+    "@spree/dashboard-core": "{{spree_dashboard_core_range}}",
+    "@spree/dashboard-ui": "{{spree_dashboard_ui_range}}",
     "@tanstack/react-query": "^5",
     "@tanstack/react-router": "^1",
     "i18next": "^26",

package/dist/templates/seller-dashboard-starter/AGENTS.md

@@ -0,0 +1,75 @@
+# Agent Instructions
+
+This is the Spree seller panel for this marketplace — a Vite + React app. The
+shell ships in `@spree/seller-dashboard`; this project holds your
+customizations. Sellers manage their own catalog and orders here.
+
+Full docs: https://spreecommerce.org/docs/developer/dashboard/overview
+
+The admin dashboard is the reference implementation: when a component is
+useful to both, extract it rather than copying it.
+
+## Imports
+
+Import from `@spree/seller-dashboard` — it re-exports the framework and the design
+system, so there is no need to work out which package an export lives in.
+
+```ts
+import { defineDashboardPlugin, useStore, Button, ResourceTable } from '@spree/seller-dashboard'
+```
+
+`@spree/dashboard-core` and `@spree/dashboard-ui` stay importable for the few
+components that exist in both: the design system's takes data as props, the
+framework's fetches its own. The facade gives you the framework's.
+
+## Where code goes
+
+Organized by kind, one file per resource — the same layout the panel
+uses internally.
+
+| Directory | Holds | Naming |
+|---|---|---|
+| `src/plugins.ts` | Registrations only: nav, slots, tables | one file |
+| `src/pages/` | One screen each | `brands.tsx` |
+| `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 map
+of what exists, not an implementation.
+
+## Rules
+
+- **The Admin API is the only data source.** Never reach into the Rails app or
+  import server-rendered HTML. Seller endpoints are scoped to the signed-in
+  seller by the server, never by the client. A missing endpoint is added to the API first.
+- **Wrap API calls in a hook.** Components never call `adminClient` directly.
+- **Query keys are store-scoped.** Build them with `useResourceKey`; a bare
+  `['brands']` key leaks one store's data into another after a store switch.
+- **Writes go through `useResourceMutation`**, which maps 422 responses onto
+  form fields instead of firing a toast.
+- **Every visible string goes through i18next** — page titles, column labels,
+  buttons, empty states, toasts. Never hardcode English in JSX or in a table
+  definition. Add each new key to every locale file the project ships.
+- **Schemas hold canonical values, never labels.** Build `{ value, label }`
+  pairs at render time so labels stay translatable.
+- **Never embed an SDK entity type in a form-values type.** React Hook Form
+  walks every nested key and the SDK's object graph overflows the TypeScript
+  compiler.
+- **A sortable or filterable column must be allowlisted for Ransack** on the
+  model, or the request fails at runtime.
+- **Destructive actions that fire straight from a click need a confirm** —
+  `useConfirm()` with `variant: 'destructive'`.
+
+## Checks
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm test        # unit tests (Vitest, Node environment)
+pnpm build
+```
+
+Test the logic between the UI and the API — query keys, payload mapping, permission predicates. Do not write tests that render a component to assert its markup; that tests React. Use `pnpm test:e2e` when a browser is genuinely needed.

package/dist/templates/seller-dashboard-starter/package.json

@@ -8,13 +8,18 @@
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --fix ."
   },
   "dependencies": {
-    "@spree/seller-dashboard": "^1.0.0-beta.2",
-    "@spree/seller-sdk": "^1.0.0-beta.2",
+    "@spree/seller-dashboard": "^1.0.0-beta.4",
+    "@spree/dashboard-core": "^1.0.0-beta.4",
+    "@spree/dashboard-ui": "^1.0.0-beta.4",
+    "@spree/seller-sdk": "^1.0.0-beta.3",
     "@tanstack/react-query": "^5.100.9",
     "@tanstack/react-router": "^1.169.2",
     "react": "^19.2.6",
@@ -22,11 +27,13 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
+    "@playwright/test": "^1.59.1",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
     "typescript": "~6.0.3",
-    "vite": "^8.0.16"
+    "vite": "^8.0.16",
+    "vitest": "^4.1.5"
   },
   "packageManager": "pnpm@11.13.1"
 }