@spree/cli 2.3.9 → 2.4.1

package/dist/templates/dashboard-starter/src/styles.css

@@ -0,0 +1,8 @@
+/* CSS entry. The Spree stylesheet chain provides Tailwind v4 layers, design
+ * tokens, and base styles; `spreeDashboardPlugin()` appends `@source`
+ * directives here at build time so Tailwind scans every Spree dashboard
+ * package and installed plugin for class usage.
+ *
+ * Add your own styles below the import. */
+
+@import "@spree/dashboard/styles.css";

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

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "ignoreDeprecations": "6.0",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

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

@@ -0,0 +1,33 @@
+import { spreeDashboardPlugin } from '@spree/dashboard/vite'
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  // Sub-path mounting for the single-node topology (Rails serves the build at
+  // /dashboard): build with VITE_BASE_PATH=/dashboard/ so asset URLs resolve.
+  // Unset (dev, CDN root deploys) Vite defaults to '/'.
+  base: process.env.VITE_BASE_PATH,
+  // spreeDashboardPlugin bundles Tailwind, injects @source directives for
+  // every Spree dashboard package, auto-discovers installed dashboard
+  // plugins (package.json deps carrying the `spree.dashboard.plugin`
+  // marker), serves the `virtual:spree-dashboard-plugins` module that
+  // src/main.tsx imports to activate them, and composes the shell's and
+  // every plugin's file routes into src/routeTree.gen.ts on each dev
+  // start/build — commit that file; its diff shows what an upgrade added.
+  plugins: [spreeDashboardPlugin(), react()],
+  // Proxy /api to the Rails server so the SPA is same-origin with the API in
+  // dev — keeps the refresh-token cookie working under SameSite=Lax without
+  // HTTPS. /rails covers Active Storage's Disk-service presigned URLs.
+  server: {
+    proxy: {
+      '/api': {
+        target: process.env.VITE_SPREE_API_URL || 'http://localhost:3000',
+        changeOrigin: true,
+      },
+      '/rails': {
+        target: process.env.VITE_SPREE_API_URL || 'http://localhost:3000',
+        changeOrigin: true,
+      },
+    },
+  },
+})

package/dist/templates/plugin/LICENSE.tt

@@ -0,0 +1,3 @@
+Copyright (c) {{year}} {{author_name}}
+
+Licensed under the {{license}} License. See the license's full text for the canonical terms.

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

@@ -0,0 +1,52 @@
+# {{plugin_name}}
+
+A Spree plugin: **{{name}}**.
+
+This is a hybrid Node/Ruby monorepo with two halves:
+
+- `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.
+
+## Development setup
+
+```bash
+# Install JavaScript dependencies
+pnpm install
+
+# Install Ruby dependencies for the engine
+cd engine && bundle install && cd ..
+```
+
+## 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
+import '{{npm_dashboard_package}}'
+```
+
+That's it — no `vite.config.ts` edit. This plugin's `package.json` declares `"spree": { "dashboard": { "plugin": true } }`, which `@spree/dashboard-core/vite`'s auto-discovery picks up so Tailwind v4 scans the plugin's source files for utility classes automatically.
+
+If you'd rather opt out of auto-discovery and register manually, pass an explicit `plugins` array to `spreeDashboardPlugin` in the host's `vite.config.ts`.
+
+## Documentation
+
+- [Dashboard overview](https://spreecommerce.org/docs/developer/dashboard/overview) — three-package split + when to plug-in vs. customize in-app
+- [Customization quickstart](https://spreecommerce.org/docs/developer/dashboard/customization/quickstart) — the registries this plugin uses
+- [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
+
+## License
+
+{{license}} © {{year}} {{author_name}}

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

@@ -0,0 +1,19 @@
+{
+  "name": "{{npm_package_name}}",
+  "private": true,
+  "version": "0.1.0",
+  "description": "Spree plugin: {{name}}",
+  "author": "{{author_name}} <{{author_email}}>",
+  "license": "{{license}}",
+  "type": "module",
+  "scripts": {
+    "build": "pnpm -r build",
+    "lint": "pnpm -r lint",
+    "typecheck": "pnpm -r typecheck",
+    "test": "pnpm -r test"
+  },
+  "packageManager": "pnpm@11.1.1",
+  "engines": {
+    "node": ">=22"
+  }
+}

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

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+  "files": {
+    "includes": ["src/**"]
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "asNeeded"
+    }
+  }
+}

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

@@ -0,0 +1,49 @@
+{
+  "name": "{{npm_dashboard_package}}",
+  "private": true,
+  "version": "0.1.0",
+  "description": "Dashboard plugin half of {{plugin_name}}",
+  "author": "{{author_name}} <{{author_email}}>",
+  "license": "{{license}}",
+  "type": "module",
+  "main": "./src/index.tsx",
+  "module": "./src/index.tsx",
+  "types": "./src/index.tsx",
+  "exports": {
+    ".": "./src/index.tsx"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "lint": "biome check src",
+    "lint:fix": "biome check --fix src",
+    "typecheck": "tsc --noEmit"
+  },
+  "spree": {
+    "dashboard": {
+      "plugin": true,
+      "routes": "./src/routes"
+    }
+  },
+  "peerDependencies": {
+    "@spree/admin-sdk": "^0.6.0",
+    "@spree/dashboard-core": "^0.10.0",
+    "@spree/dashboard-ui": "^0.10.0",
+    "@tanstack/react-query": "^5",
+    "@tanstack/react-router": "^1",
+    "i18next": "^26",
+    "lucide-react": "^1",
+    "react": "^19",
+    "react-dom": "^19",
+    "react-i18next": "^17"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "~6.0.3",
+    "vite": "^8"
+  }
+}

package/dist/templates/plugin/packages/dashboard/src/client.ts.tt

@@ -0,0 +1,29 @@
+/**
+ * Typed wrappers around `adminClient.request` for the {{name}} endpoints
+ * shipped by the engine. Keeping the wrappers in one file means consumers
+ * (route pages, slot widgets) never call `request` directly — they import
+ * from here, which makes it easy to swap implementations or rename paths.
+ *
+ * See https://spreecommerce.org/docs/developer/sdk/admin/extending for the
+ * underlying `request` API.
+ */
+import type { PaginatedResponse } from '@spree/admin-sdk'
+import { adminClient } from '@spree/dashboard-core'
+import type { {{module_name}}, {{module_name}}CreateParams, {{module_name}}UpdateParams } from './types'
+
+type ListParams = Record<string, string | number | boolean | (string | number)[] | undefined>
+
+export const {{module_name}}Client = {
+  list: (params?: ListParams) =>
+    adminClient.request<PaginatedResponse<{{module_name}}>>('GET', '/{{name}}', { params }),
+
+  get: (id: string) => adminClient.request<{{module_name}}>('GET', `/{{name}}/${id}`),
+
+  create: (body: {{module_name}}CreateParams) =>
+    adminClient.request<{{module_name}}>('POST', '/{{name}}', { body }),
+
+  update: (id: string, body: {{module_name}}UpdateParams) =>
+    adminClient.request<{{module_name}}>('PATCH', `/{{name}}/${id}`, { body }),
+
+  delete: (id: string) => adminClient.request<void>('DELETE', `/{{name}}/${id}`),
+}

package/dist/templates/plugin/packages/dashboard/src/index.tsx.tt

@@ -0,0 +1,89 @@
+/**
+ * {{plugin_name}} — dashboard plugin entry.
+ *
+ * Wires nav + route + slot + table extensions via defineDashboardPlugin and
+ * merges plugin translations into the dashboard's i18next namespace.
+ *
+ * Activation is automatic: the package.json's `spree.dashboard.plugin`
+ * marker makes `spreeDashboardPlugin()` discover this package and import it
+ * through `virtual:spree-dashboard-plugins` in the host's app entry, running
+ * every defineDashboardPlugin and i18n.addResourceBundle call below before
+ * the router mounts. Hosts without the virtual import can side-effect-import
+ * '{{npm_dashboard_package}}' directly.
+ */
+import { defineDashboardPlugin, defineTable, i18n } from '@spree/dashboard-core'
+import { RelativeTime } from '@spree/dashboard-ui'
+import { PackageIcon } from 'lucide-react'
+import { {{module_name}}Client } from './client'
+import en from './locales/en.json'
+import { {{module_name}}Card } from './slots/product-{{name}}-card'
+import type { {{module_name}} } from './types'
+
+// ---------------------------------------------------------------------------
+// 1. Translations
+// ---------------------------------------------------------------------------
+// `deep: true` + `overwrite: true` merge our `admin.{{name}}_plugin.*` keys
+// into the framework's `admin.*` namespace without dropping base translations.
+i18n.addResourceBundle('en', 'translation', en, true, true)
+
+// ---------------------------------------------------------------------------
+// 2. Declare the table used by our list page
+// ---------------------------------------------------------------------------
+defineTable<{{module_name}}>('{{name}}', {
+  title: i18n.t('admin.{{name}}_plugin.table.title'),
+  searchParam: 'search',
+  searchPlaceholder: i18n.t('admin.{{name}}_plugin.table.search_placeholder'),
+  defaultSort: { field: 'name', direction: 'asc' },
+  emptyMessage: i18n.t('admin.{{name}}_plugin.table.empty'),
+  columns: [
+    {
+      key: 'name',
+      label: i18n.t('admin.{{name}}_plugin.fields.name'),
+      sortable: true,
+      filterable: true,
+      default: true,
+      // Add a detail route (path: '/{{name}}/$id') before linking here —
+      // see /developer/dashboard/customization/routes.
+      render: (record) => <span className="font-medium text-foreground">{record.name}</span>,
+    },
+    {
+      key: 'created_at',
+      label: i18n.t('admin.{{name}}_plugin.fields.created_at'),
+      sortable: true,
+      default: true,
+      render: (record) => <RelativeTime iso={record.created_at} />,
+    },
+  ],
+})
+
+// ---------------------------------------------------------------------------
+// 3. Register everything else
+// ---------------------------------------------------------------------------
+defineDashboardPlugin({
+  nav: [
+    {
+      key: '{{name}}',
+      label: i18n.t('admin.{{name}}_plugin.nav'),
+      path: '/{{name}}',
+      icon: PackageIcon,
+      position: 50,
+    },
+  ],
+  // Routes ship as file routes in src/routes/ (see the package.json marker)
+  // and are compiled into the host's typed route tree. The `routes:` registry
+  // option remains available for dynamic host-app cases.
+  slots: {
+    'product.form_sidebar': [
+      {
+        id: '{{name}}-card',
+        // dashboard-core types `slots` generically; the slot's context shape
+        // is documented in @spree/dashboard's source per slot name.
+        component: {{module_name}}Card as never,
+        position: 250,
+      },
+    ],
+  },
+})
+
+export { {{module_name}}Client } from './client'
+export type { {{module_name}} } from './types'

package/dist/templates/plugin/packages/dashboard/src/locales/en.json.tt

@@ -0,0 +1,25 @@
+{
+  "admin": {
+    "{{name}}_plugin": {
+      "nav": "{{module_name}}",
+      "page": {
+        "title": "{{module_name}}",
+        "subtitle": "Manage your {{name}}",
+        "new_cta": "New {{name}}"
+      },
+      "table": {
+        "title": "{{module_name}}",
+        "search_placeholder": "Search by name…",
+        "empty": "No {{name}} yet"
+      },
+      "fields": {
+        "name": "Name",
+        "created_at": "Created"
+      },
+      "product_card": {
+        "title": "{{module_name}}",
+        "placeholder": "Replace this widget with your own slot UI."
+      }
+    }
+  }
+}

package/dist/templates/plugin/packages/dashboard/src/pages/{{name}}-list.tsx.tt

@@ -0,0 +1,50 @@
+/**
+ * {{module_name}} list page. Mounted at `/$storeId/{{name}}` via the plugin's
+ * route registration in `index.tsx`. Uses `<ResourceTable>` for filtering,
+ * sorting, pagination — the same UX as core's Products/Customers/Orders.
+ *
+ * Plugin route components receive `{ params, storeId, searchParams }` from
+ * the dashboard's catch-all dispatcher. We forward `searchParams` to
+ * ResourceTable so filter/sort/pagination round-trip through the URL.
+ */
+import { PageHeader, type ResourceSearch, ResourceTable } from '@spree/dashboard-core'
+import { Button, ResourceLayout } from '@spree/dashboard-ui'
+import { PlusIcon } from 'lucide-react'
+import { useTranslation } from 'react-i18next'
+import { {{module_name}}Client } from '../client'
+import type { {{module_name}} } from '../types'
+
+interface {{module_name}}ListPageProps {
+  searchParams: Record<string, unknown>
+}
+
+export function {{module_name}}ListPage({ searchParams }: {{module_name}}ListPageProps) {
+  const { t } = useTranslation()
+
+  return (
+    <ResourceLayout
+      header={
+        <PageHeader
+          title={t('admin.{{name}}_plugin.page.title')}
+          subtitle={t('admin.{{name}}_plugin.page.subtitle')}
+          actions={
+            <Button size="sm">
+              <PlusIcon className="size-4" />
+              {t('admin.{{name}}_plugin.page.new_cta')}
+            </Button>
+          }
+        />
+      }
+      main={
+        <ResourceTable<{{module_name}}>
+          tableKey="{{name}}"
+          queryKey="{{name}}"
+          // ResourceTable hands `params` to queryFn as Record<string, unknown>;
+          // we narrow to our client's known param shape at the boundary.
+          queryFn={(params) => {{module_name}}Client.list(params as Record<string, never>)}
+          searchParams={searchParams as ResourceSearch}
+        />
+      }
+    />
+  )
+}

package/dist/templates/plugin/packages/dashboard/src/routes/{{name}}.index.tsx.tt

@@ -0,0 +1,26 @@
+/**
+ * File route for the {{name}} list — compiled into the host's typed route
+ * tree by `spreeDashboardPlugin()`. This directory is declared via the
+ * package.json marker (`"spree": { "dashboard": { "routes": "./src/routes" } }`).
+ *
+ * The path literal is the FINAL composed path (plugin routes mount under the
+ * dashboard's `_authenticated/$storeId` layout) — commit it exactly; the
+ * route generator verifies it.
+ *
+ * Route files type-check through a host app's build (they need a generated
+ * route tree in the program), so they're excluded from this package's
+ * standalone `tsc` run — develop against a dashboard host.
+ */
+import { resourceSearchSchema } from '@spree/dashboard-core'
+import { createFileRoute } from '@tanstack/react-router'
+import { {{module_name}}ListPage } from '../pages/{{name}}-list'
+
+export const Route = createFileRoute('/_authenticated/$storeId/{{name}}/')({
+  validateSearch: resourceSearchSchema,
+  component: {{module_name}}Route,
+})
+
+function {{module_name}}Route() {
+  const searchParams = Route.useSearch()
+  return <{{module_name}}ListPage searchParams={searchParams} />
+}

package/dist/templates/plugin/packages/dashboard/src/slots/product-{{name}}-card.tsx.tt

@@ -0,0 +1,33 @@
+/**
+ * Sidebar widget rendered on the product detail page via the
+ * `product.form_sidebar` slot. Demonstrates the slot extension pattern:
+ * the host page knows nothing about {{name}}; the plugin contributes
+ * this card via the slot registry.
+ *
+ * The slot's context (typed by the dashboard's slot catalogue as
+ * `{ product }`) gives us the product being edited.
+ */
+import { Card, CardContent, CardHeader, CardTitle } from '@spree/dashboard-ui'
+import { useTranslation } from 'react-i18next'
+
+interface {{module_name}}CardProps {
+  product: { id: string }
+}
+
+export function {{module_name}}Card({ product }: {{module_name}}CardProps) {
+  const { t } = useTranslation()
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{t('admin.{{name}}_plugin.product_card.title')}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <p className="text-sm text-muted-foreground">
+          {t('admin.{{name}}_plugin.product_card.placeholder')}
+        </p>
+        <p className="mt-2 text-xs font-mono text-muted-foreground">{product.id}</p>
+      </CardContent>
+    </Card>
+  )
+}

package/dist/templates/plugin/packages/dashboard/src/types.ts.tt

@@ -0,0 +1,17 @@
+/**
+ * Shape of a {{module_name}} record returned by the engine. Generated by hand
+ * here; a real plugin should regenerate this from the Alba serializer via
+ * Spree's Typelizer pipeline once the engine is publishing types.
+ */
+export interface {{module_name}} {
+  id: string
+  name: string
+  created_at: string
+  updated_at: string
+}
+
+export interface {{module_name}}CreateParams {
+  name: string
+}
+
+export type {{module_name}}UpdateParams = Partial<{{module_name}}CreateParams>

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

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "ignoreDeprecations": "6.0",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src"],
+  "exclude": ["src/routes"]
+}

package/dist/templates/plugin/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - "packages/*"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/cli",
-  "version": "2.3.9",
+  "version": "2.4.1",
   "description": "CLI for managing Spree Commerce projects",
   "type": "module",
   "bin": {
@@ -45,13 +45,13 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
     "yaml": "^2.8.4",
-    "@spree/admin-sdk": "^0.5.0"
+    "@spree/admin-sdk": "^0.6.0"
   },
   "engines": {
     "node": ">=20"
   },
   "scripts": {
-    "build": "node scripts/bundle-spec.mjs && tsup",
+    "build": "node scripts/bundle-spec.mjs && node ../../scripts/sync-dashboard-starter.mjs templates/dashboard-starter && tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",