Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Refresh dashboard docs and package READMEs for external readers

Damian Legawiecc7267123f709
diff --git a/docs/developer/dashboard/customization/navigation.mdx b/docs/developer/dashboard/customization/navigation.mdx
index e145a54455..4fece95409 100644
--- a/docs/developer/dashboard/customization/navigation.mdx
+++ b/docs/developer/dashboard/customization/navigation.mdx
@@ -24,7 +24,7 @@ nav.add({
})
```
-`position` controls ordering — built-ins use 100–600 (Home 100, Orders 200, Products 300, Customers 400, Promotions 500, Reports 600), leaving gaps to slot into. The default is 100. Keys must be unique, including against those built-in keys — duplicates throw at boot.
+`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`
@@ -131,6 +131,24 @@ nav.add({
})
```
+### 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.
diff --git a/docs/developer/dashboard/customization/quickstart.mdx b/docs/developer/dashboard/customization/quickstart.mdx
index b66b50f019..d5070a9fa2 100644
--- a/docs/developer/dashboard/customization/quickstart.mdx
+++ b/docs/developer/dashboard/customization/quickstart.mdx
@@ -7,7 +7,7 @@ description: Add your first customization to the Spree dashboard in under 5 minu
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/`; it can also be a standalone clone of the [dashboard starter](https://github.com/spree/dashboard-starter). Start it with `pnpm dev`.
+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`); it can also be a standalone clone of the [dashboard starter](https://github.com/spree/dashboard-starter). 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](/developer/dashboard/plugins/overview).
@@ -82,7 +82,7 @@ defineDashboardPlugin({
Save. Click "Analytics" — your page renders inside the dashboard chrome, at `/<store id>/analytics`.
<Warning>
-Every `key` must be unique, including against the built-ins (`home`, `orders`, `products`, `customers`, `promotions`, `reports`, `settings`). Registering a duplicate key throws at boot with a message naming the conflict.
+Every `key` must be unique, including against the built-ins (`getting-started`, `home`, `orders`, `products`, `customers`, `promotions`, `reports`, `settings`). Registering a duplicate key throws at boot with a message naming the conflict.
</Warning>
## What just happened
diff --git a/docs/developer/dashboard/overview.mdx b/docs/developer/dashboard/overview.mdx
index d76f47f1bf..5a9c2d7139 100644
--- a/docs/developer/dashboard/overview.mdx
+++ b/docs/developer/dashboard/overview.mdx
@@ -8,7 +8,7 @@ description: How the React Dashboard is structured, how to customize existing sc
The React Dashboard is a Developer Preview — APIs may still change between releases. In Spree 6 it becomes the default admin interface.
</Info>
-The React Dashboard is a single-page application (SPA) using Spree Admin API and built on three packages:
+The React Dashboard is a single-page application (SPA) that talks to the Spree Admin API and is built on three packages:
| Package | What it contains | When you touch it |
|---|---|---|
@@ -18,6 +18,15 @@ The React Dashboard is a single-page application (SPA) using Spree Admin API and
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.
+## 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.
diff --git a/packages/cli/src/commands/plugin.ts b/packages/cli/src/commands/plugin.ts
index b355995ac4..68cf05a400 100644
--- a/packages/cli/src/commands/plugin.ts
+++ b/packages/cli/src/commands/plugin.ts
@@ -455,7 +455,7 @@ function printNextSteps(answers: Answers, dst: string, installed: boolean): void
` Edit ${pc.cyan('packages/dashboard/src/index.tsx')} to wire your nav/route/slot extensions.`,
)
lines.push(
- ` See ${pc.cyan('https://docs.spreecommerce.org/developer/dashboard/plugins/overview')}`,
+ ` See ${pc.cyan('https://spreecommerce.org/docs/developer/dashboard/plugins/overview')}`,
)
}
if (answers.includeEngine) {
@@ -465,7 +465,7 @@ function printNextSteps(answers: Answers, dst: string, installed: boolean): void
` Edit ${pc.cyan(`engine/app/controllers/spree/api/v3/admin/${answers.rubyName}_controller.rb`)}`,
)
lines.push(
- ` See ${pc.cyan('https://docs.spreecommerce.org/developer/customization/extensions')}`,
+ ` See ${pc.cyan('https://spreecommerce.org/docs/developer/contributing/creating-an-extension')}`,
)
}
lines.push('')
diff --git a/packages/cli/templates/plugin/README.md.tt b/packages/cli/templates/plugin/README.md.tt
index 7ae7539705..907b87e247 100644
--- a/packages/cli/templates/plugin/README.md.tt
+++ b/packages/cli/templates/plugin/README.md.tt
@@ -40,12 +40,12 @@ If you'd rather opt out of auto-discovery and register manually, pass an explici
## Documentation
-- [Dashboard overview](https://docs.spreecommerce.org/developer/dashboard/overview) — three-package split + when to plug-in vs. customize in-app
-- [Customization quickstart](https://docs.spreecommerce.org/developer/dashboard/customization/quickstart) — the registries this plugin uses
-- [Plugin overview](https://docs.spreecommerce.org/developer/dashboard/plugins/overview) — packaging + publishing your plugin to npm
-- [Slots catalog](https://docs.spreecommerce.org/developer/dashboard/slots-catalog) — every named slot the dashboard exposes
-- [Custom Admin Endpoints](https://docs.spreecommerce.org/developer/sdk/admin/extending) — adding your own API endpoints
-- [Spree Extensions guide](https://docs.spreecommerce.org/developer/customization/extensions) — the Rails-engine side
+- [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
diff --git a/packages/cli/templates/plugin/packages/dashboard/src/client.ts.tt b/packages/cli/templates/plugin/packages/dashboard/src/client.ts.tt
index 65b407a891..41c4cd2175 100644
--- a/packages/cli/templates/plugin/packages/dashboard/src/client.ts.tt
+++ b/packages/cli/templates/plugin/packages/dashboard/src/client.ts.tt
@@ -4,7 +4,7 @@
* (route pages, slot widgets) never call `request` directly — they import
* from here, which makes it easy to swap implementations or rename paths.
*
- * See https://docs.spreecommerce.org/developer/sdk/admin/extending for the
+ * See https://spreecommerce.org/docs/developer/sdk/admin/extending for the
* underlying `request` API.
*/
import type { PaginatedResponse } from '@spree/admin-sdk'
diff --git a/packages/create-spree-app/README.md b/packages/create-spree-app/README.md
index 6d0aa72473..f74e0f1472 100644
--- a/packages/create-spree-app/README.md
+++ b/packages/create-spree-app/README.md
@@ -118,7 +118,7 @@ npx spree api-key list # List API keys
## Learn More
-- [Spree Documentation](https://docs.spreecommerce.org)
+- [Spree Documentation](https://spreecommerce.org/docs)
## License
diff --git a/packages/dashboard-core/README.md b/packages/dashboard-core/README.md
index 56e928daa0..03bb8bf5bb 100644
--- a/packages/dashboard-core/README.md
+++ b/packages/dashboard-core/README.md
@@ -354,7 +354,7 @@ registerSlot<{ product: { id: string; wishlist_count: number } }>('product.form_
})
```
-Built-in slot names match the legacy Rails admin's `render_admin_partials` mental model (e.g. `product.form_sidebar`, `order.page_body`, `product.actions`). The full list is documented per route in `@spree/dashboard`.
+Built-in slot names follow a `resource.location` convention (e.g. `product.form_sidebar`, `order.page_body`, `product.actions`). The full list lives in the [slots catalog](https://spreecommerce.org/docs/developer/dashboard/slots-catalog).
### `tables` — list-view column extensions
diff --git a/packages/dashboard-starter/README.md b/packages/dashboard-starter/README.md
index af83b19ce5..2819f33c80 100644
--- a/packages/dashboard-starter/README.md
+++ b/packages/dashboard-starter/README.md
@@ -1,6 +1,6 @@
# Spree Dashboard Starter
-The host app for the [Spree React Dashboard](https://docs.spreecommerce.org/developer/dashboard/overview) — the admin for your Spree store. `@spree/dashboard` is the actual app shell (routes, chrome, resource pages); this project is your customization point: plugins, your own pages, theming, and deployment config.
+The host app for the [Spree React Dashboard](https://spreecommerce.org/docs/developer/dashboard/overview) — the admin for your Spree store. `@spree/dashboard` is the actual app shell (routes, chrome, resource pages); this project is your customization point: plugins, your own pages, theming, and deployment config.
> **Monorepo note.** The canonical source of this template lives at `packages/dashboard-starter` in [spree/spree](https://github.com/spree/spree), where its Spree dependencies resolve via the pnpm workspace and `@spree/dashboard-plugin-example` is installed as a devDependency — booting it here doubles as the end-to-end test for the plugin pipeline. A release job syncs it to the `spree/dashboard-starter` template repo with published package versions, which is what `create-spree-app` and `spree add dashboard` clone.
@@ -25,7 +25,7 @@ That's the whole install. `spreeDashboardPlugin()` (see `vite.config.ts`) discov
## Customize
-`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://docs.spreecommerce.org/developer/dashboard/customization/quickstart).
+`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).
## Build & deploy
diff --git a/packages/dashboard-ui/README.md b/packages/dashboard-ui/README.md
index 0dea1c459e..c83d36745e 100644
--- a/packages/dashboard-ui/README.md
+++ b/packages/dashboard-ui/README.md
@@ -2,9 +2,9 @@
Spree Dashboard design system. Shadcn primitives + headless composed components + design tokens.
-> **Phase 0 placeholder.** The package is scaffolded with its target structure, but the components haven't been extracted yet. See `docs/plans/6.0-admin-spa.md` → "Package Split" for the phased plan.
+> **Developer Preview.** APIs may change between 0.x releases. Docs: [React Dashboard](https://spreecommerce.org/docs/developer/dashboard/overview).
-## What goes here
+## What's inside
- `src/ui/` — shadcn primitives (Button, Input, Dialog, Sheet, Table, …). Copy-paste owned: fork into your own project as needed.
- `src/spree/` — composed components built on the primitives (PageHeader, ResourceTable, AppSidebar, …). **All headless: data and callbacks come in via props.** No provider imports, no hook calls, no SDK access.
@@ -15,11 +15,11 @@ The headless rule is what makes the components composable from outside `@spree/d
## Source-only package
-This package ships **TypeScript source**, not a compiled bundle. Consumers compile it through their own Vite + Tailwind setup. This is required because Tailwind v4 scans source files in the consuming app for utility classes; a pre-compiled CSS bundle would miss classes only used by source-imported components.
+This package ships **TypeScript source**, not a compiled bundle. Consumers compile it through their own Vite + Tailwind setup. This is required because Tailwind v4 scans source files in the consuming app for utility classes; a pre-compiled CSS bundle would miss classes only used by source-imported components. The `spreeDashboardPlugin` from `@spree/dashboard-core/vite` wires the scanning up for you.
## Peer dependencies
-`react` and `react-dom` are peer deps. The consumer provides them.
+The consuming app provides `react`, `react-dom`, `@tanstack/react-router`, `@tanstack/react-hotkeys`, `react-hook-form`, `i18next`, and `react-i18next` — see `peerDependencies` in `package.json` for the exact ranges.
## What's NOT here
diff --git a/packages/dashboard/README.md b/packages/dashboard/README.md
index 1b08cee060..eaee85f870 100644
--- a/packages/dashboard/README.md
+++ b/packages/dashboard/README.md
@@ -1,10 +1,10 @@
# @spree/dashboard
-The Spree Commerce admin dashboard — a React single-page application that replaces the legacy Rails `spree/admin` engine entirely. Built on the [Admin API](https://spreecommerce.org/docs/api-reference/admin-api/introduction) via `@spree/admin-sdk`, with a modern extension model (table registry, navigation registry, component injection) for plugin authors.
+The Spree Commerce admin dashboard (the "React Dashboard") — a React single-page application that replaces the Classic Admin (the server-rendered Rails engine). Built on the [Admin API](https://spreecommerce.org/docs/api-reference/admin-api/introduction) via `@spree/admin-sdk`, with an extension model (table registry, navigation registry, slots, typed plugin routes) for plugin authors.
-Part of the three-package dashboard stack — see [`packages/README.md`](../README.md) for how `@spree/dashboard`, `@spree/dashboard-ui`, and `@spree/dashboard-core` fit together.
+Part of the three-package dashboard stack with [`@spree/dashboard-core`](https://github.com/spree/spree/tree/main/packages/dashboard-core) (the framework and extension API) and [`@spree/dashboard-ui`](https://github.com/spree/spree/tree/main/packages/dashboard-ui) (the design system).
-> **Developer Preview.** The Admin SPA is in active development for Spree 6.0. Some routes still fall back to the Rails admin while feature parity is being reached. See [`docs/plans/6.0-admin-spa.md`](../../docs/plans/6.0-admin-spa.md) for the current scope.
+> **Developer Preview.** APIs may change between 0.x releases; in Spree 6 the React Dashboard becomes the default admin. Docs: [React Dashboard](https://spreecommerce.org/docs/developer/dashboard/overview).
## Tech stack
@@ -131,7 +131,7 @@ src/
### Authentication
-JWT access token in memory + refresh token in an HttpOnly signed cookie. See `docs/plans/5.5-admin-auth-cookie-refresh.md` for the full design.
+JWT access token in memory + refresh token in an HttpOnly signed cookie.
- Login → `POST /api/v3/admin/auth/login` returns `{ token, user }`. The server also sets `spree_admin_refresh_token` — an HttpOnly signed cookie scoped to `/api/v3/admin/auth`, invisible to JS.
- Access token stays in React state only — **no `localStorage`**, no `sessionStorage`.
@@ -141,7 +141,7 @@ JWT access token in memory + refresh token in an HttpOnly signed cookie. See `do
- Logout → `POST /api/v3/admin/auth/logout` destroys the refresh-token row server-side and clears the cookie. The in-memory state is cleared regardless of whether the network call succeeds.
- Concurrent refresh attempts are serialized to prevent double-rotation under StrictMode/HMR.
-CSRF defense comes from the cookie's `SameSite` attribute combined with the `Spree::AllowedOrigin` allowlist enforced via `Rack::Cors`. There is no double-submit CSRF token — see the plan doc for the reasoning.
+CSRF defense comes from the cookie's `SameSite` attribute combined with the `Spree::AllowedOrigin` allowlist enforced via `Rack::Cors`. There is no double-submit CSRF token.
Public routes (login) sit at the root; everything else is gated by `routes/_authenticated.tsx`.
@@ -152,8 +152,7 @@ In dev, `vite.config.ts` proxies `/api/*` → `http://localhost:3000` so the SPA
Permissions are **server-driven**. On login, `GET /api/v3/admin/me` returns the user's CanCanCan abilities serialized as JSON. The SPA mirrors them via:
```tsx
-import { Can } from '@/components/can'
-import { usePermissions } from '@/providers/permission-provider'
+import { Can, usePermissions } from '@spree/dashboard-core'
// Declarative
<Can I="update" a="Order"><EditButton /></Can>
@@ -171,11 +170,12 @@ All authenticated routes include a `$storeId` segment (e.g. `/store_abc/orders`)
### Extension points
-Three extension points are designed for plugin authors (full design in [`docs/plans/6.0-admin-spa.md`](../../docs/plans/6.0-admin-spa.md)):
+Extension points for plugin authors (see the [customization docs](https://spreecommerce.org/docs/developer/dashboard/customization/quickstart)):
1. **Table registry** — register columns/filters/actions for any list view
-2. **Navigation registry** — inject sidebar menu items
-3. **Component injection** — slot points in core pages (e.g., extra cards on the order detail)
+2. **Navigation registry** — inject sidebar menu items, including under built-in menus
+3. **Slots** — inject components into core pages (e.g., extra cards on the order detail)
+4. **Typed file routes** — plugin pages compiled into the host's route tree with type-checked links
The shadcn copy-paste model means UI components in `src/components/ui/` are owned by this project, not a component library. Extensions can copy-and-modify rather than fighting library abstractions.
@@ -189,16 +189,16 @@ Components land in `src/components/ui/`. Customize freely.
## Working with @spree/admin-sdk
-All API calls go through the SDK instance configured in `src/client.ts`. Wrap calls in custom hooks under `src/hooks/`:
+All API calls go through the `adminClient` singleton from `@spree/dashboard-core`. Wrap calls in custom hooks under `src/hooks/`:
```ts
// src/hooks/use-orders.ts
+import { adminClient, useResourceKey } from '@spree/dashboard-core'
import { useQuery } from '@tanstack/react-query'
-import { adminClient } from '@/client'
export function useOrders(params: ListOrdersParams) {
return useQuery({
- queryKey: ['orders', params],
+ queryKey: useResourceKey('orders', params),
queryFn: () => adminClient.orders.list(params),
})
}
@@ -208,7 +208,7 @@ Mutations follow the same pattern with `useMutation` and `queryClient.invalidate
## End-to-end tests
-The `e2e/` folder holds [Playwright](https://playwright.dev/) specs that drive the SPA against a real Rails backend — no API mocks. CI runs the same suite via the `admin-e2e` job in `.github/workflows/packages.yml`; locally, `pnpm test:e2e` mirrors what CI does.
+The `e2e/` folder holds [Playwright](https://playwright.dev/) specs that drive the SPA against a real Rails backend — no API mocks. CI runs the same suite via the `dashboard-e2e` job in `.github/workflows/packages.yml`; locally, `pnpm test:e2e` mirrors what CI does.
What the suite boots:
@@ -263,7 +263,7 @@ Specs live next to the existing ones in `e2e/`. Use `getCredentials()` from `e2e
## Contributing
-This package is private and ships as part of the Spree 6.0 release. Architecture decisions live in `docs/plans/6.0-admin-spa.md` — please read that before proposing significant changes.
+Development happens in the [spree/spree](https://github.com/spree/spree) monorepo under `packages/dashboard`. Architecture decisions live in `docs/plans/6.0-admin-spa.md` there — please read that before proposing significant changes.
When changing API contracts, also update the upstream serializers in `spree/api` and regenerate types: