React Dashboard Overview

The React Dashboard is a React single-page application (SPA) that talks to the Spree Admin API. 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:

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.

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/):

// 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.

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)
• 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 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. (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:

npx @spree/cli plugin new my-feature

→ Start at the plugin scaffolding guide.

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
• Plugin scaffolding
• Slots catalog — every named slot the dashboard exposes
• @spree/dashboard-core README — full extension API reference
• Classic Admin extension model — for Spree 5.x