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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Introduce `@spree/dashboard-vite` plugin (#14114)
Damian Legawiec1a1a1b2cba74
diff --git a/packages/dashboard-core/README.md b/packages/dashboard-core/README.mdindex 358fc6a3fc..b5e3497690 100644--- a/packages/dashboard-core/README.md+++ b/packages/dashboard-core/README.md@@ -60,6 +60,115 @@ Peer dependencies that the consuming app provides: `react`, `react-dom`, `@spree└── defineDashboardPlugin # the one-call extension facade```+Additional entry point:++- `@spree/dashboard-core/vite` — Vite plugin that wires Tailwind v4. See [Vite integration](#vite-integration).++## Vite integration++The dashboard relies on Tailwind v4, which doesn't scan `node_modules` by default and only accepts filesystem paths in `@source` directives (not bare package specifiers). The `spreeDashboardPlugin` from `@spree/dashboard-core/vite` resolves each Spree dashboard package and each host-named plugin through Node module resolution and injects matching `@source` directives into your CSS entry at build time. It also bundles `@tailwindcss/vite` itself so plugin ordering is guaranteed — hosts must NOT register `@tailwindcss/vite` separately.++### Using the full `@spree/dashboard` app shell++```ts+// host vite.config.ts+import { spreeDashboardPlugin } from '@spree/dashboard-core/vite'+import { TanStackRouterVite } from '@tanstack/router-plugin/vite'+import react from '@vitejs/plugin-react'+import { defineConfig } from 'vite'++export default defineConfig({+ plugins: [+ spreeDashboardPlugin({+ plugins: [+ '@my-store/orders-dashboard-plugin',+ '@my-store/wishlists-dashboard-plugin',+ ],+ }),+ TanStackRouterVite(),+ react(),+ ],+})+```++```css+/* host src/styles.css */+@import "@spree/dashboard/styles.css";+```++### Building a custom dashboard on `@spree/dashboard-core` + `@spree/dashboard-ui`++If you're not using `@spree/dashboard`'s app shell — e.g. a vendor portal or B2B buyer admin built directly on the registries and primitives — point `cssEntry` at your own CSS file:++```ts+// custom-dashboard vite.config.ts+import { spreeDashboardPlugin } from '@spree/dashboard-core/vite'++export default defineConfig({+ plugins: [+ spreeDashboardPlugin({+ cssEntry: './src/admin.css',+ plugins: ['@my-store/vendor-portal-plugin'],+ }),+ // host owns react, router, etc.+ ],+})+```++```css+/* custom-dashboard src/admin.css */+@import "@spree/dashboard-ui/styles.css";+/* Tailwind auto-scans the host's own src/, so host-authored classes+ work without configuration. The Vite plugin injects @source for+ @spree/dashboard-core, @spree/dashboard-ui, and any named plugins. */+```++### `@spree/dashboard-ui` only (no `@spree/dashboard-core`)++If you only need design-system primitives and tokens, no registries, no providers — you don't need this Vite plugin at all. Install `@spree/dashboard-ui`, set up `@tailwindcss/vite` yourself, and import its stylesheet:++```css+@import "@spree/dashboard-ui/styles.css";+```++`dashboard-ui/styles.css` carries its own `@source` directives covering its components.++### Options++```ts+spreeDashboardPlugin({+ /**+ * Path to the host's CSS entry file, relative to the host's project root.+ * The plugin injects @source directives into this file. Defaults to+ * `./src/styles.css`.+ */+ cssEntry: './src/styles.css',++ /**+ * Names of installed dashboard plugin packages. Each must be a resolvable+ * npm specifier. The plugin resolves each via Node module resolution and+ * tells Tailwind to scan its source files.+ */+ plugins: ['@my-store/orders-plugin'],+})+```++### What plugin authors must do++Ship `src/` in their published package so Tailwind has source files to scan:++```json+// plugin's package.json+{+ "name": "@my-store/orders-dashboard-plugin",+ "main": "./src/index.ts",+ "types": "./src/index.ts",+ "files": ["src", "README.md"]+}+```++Plugin authors do NOT need to ship pre-built CSS, configure Tailwind, or care about the host's package manager — adding the plugin name to the host's `plugins: [...]` is enough.+## Plugin authoring — the basicsYour plugin is an npm package. Its entry module calls `defineDashboardPlugin({...})` at import time. The dashboard app imports your entry module before first render — every registry handles late registration via `useSyncExternalStore`, so even if your plugin loads asynchronously the sidebar/slots re-render.diff --git a/packages/dashboard-core/package.json b/packages/dashboard-core/package.jsonindex 9a8ea7fc52..b37c3dcf09 100644--- a/packages/dashboard-core/package.json+++ b/packages/dashboard-core/package.json@@ -11,6 +11,7 @@"exports": {".": "./src/index.ts","./plugin": "./src/plugin.ts",+ "./vite": "./src/vite/index.ts","./providers/*": "./src/providers/*.tsx","./hooks/*": "./src/hooks/*.ts","./hooks/use-command-palette": "./src/hooks/use-command-palette.tsx",@@ -45,6 +46,7 @@"@dnd-kit/core": "^6.3.1","@dnd-kit/sortable": "^10.0.0","@dnd-kit/utilities": "^3.2.2",+ "@tailwindcss/vite": "^4.2.4","lucide-react": "^1.14.0","spark-md5": "^3.0.2","zod": "^4.4.3"diff --git a/packages/dashboard-core/src/vite/index.ts b/packages/dashboard-core/src/vite/index.tsnew file mode 100644index 0000000000..6b2adbc839--- /dev/null+++ b/packages/dashboard-core/src/vite/index.ts@@ -0,0 +1,148 @@+import fs from 'node:fs'+import { createRequire } from 'node:module'+import path from 'node:path'+import { fileURLToPath } from 'node:url'+import tailwindcss from '@tailwindcss/vite'+import type { Plugin, PluginOption } from 'vite'++export interface SpreeDashboardPluginOptions {+ /**+ * Path to the host app's CSS entry file (the one that does+ * `@import "@spree/dashboard-ui/styles.css"`). Resolved relative to the+ * host's project root. The plugin injects `@source` directives into this+ * file so Tailwind v4 scans every Spree dashboard package and every+ * dashboard plugin for class usage.+ *+ * Defaults to `./src/styles.css`, which fits the conventional Vite layout.+ */+ cssEntry?: string++ /**+ * Names of dashboard plugin packages installed in the host app. Each name+ * must be a resolvable npm package specifier — the same string you'd pass+ * to `import()`. The plugin resolves each one via Node module resolution+ * and tells Tailwind v4 to scan its source files for class usage.+ *+ * Example: `['@my-store/orders-plugin', '@my-store/wishlists-plugin']`.+ */+ plugins?: string[]+}++/**+ * Vite plugin that wires up Tailwind v4 for a Spree dashboard.+ *+ * Combines two concerns:+ *+ * 1. Source-scanning: tells Tailwind to scan `@spree/dashboard-core`,+ * `@spree/dashboard-ui`, and any host-named plugin packages, by+ * injecting `@source` directives into the host's CSS entry. Tailwind v4+ * doesn't scan `node_modules` by default and only accepts filesystem+ * paths in `@source` directives (not bare package specifiers), so we+ * resolve each package through Node module resolution to get an+ * absolute path that works under any package layout (workspace+ * symlinks, npm tarballs, pnpm's `.pnpm/` hoisting).+ *+ * 2. Tailwind itself: returns `@tailwindcss/vite` bundled alongside the+ * source-injection plugin, in the right order. Hosts don't add+ * `@tailwindcss/vite` separately.+ *+ * Usage from a host using the full `@spree/dashboard` app shell:+ *+ * // host vite.config.ts+ * import { spreeDashboardPlugin } from '@spree/dashboard-core/vite'+ *+ * export default defineConfig({+ * plugins: [+ * spreeDashboardPlugin({+ * plugins: ['@my-store/orders-plugin'],+ * }),+ * // … react(), TanStack Router, etc. — host owns these.+ * ],+ * })+ *+ * For a custom dashboard built on `@spree/dashboard-core` + `@spree/dashboard-ui`,+ * point `cssEntry` at the host's own CSS file:+ *+ * spreeDashboardPlugin({+ * cssEntry: './src/admin.css',+ * plugins: ['@my-store/vendor-portal-plugin'],+ * })+ */+export function spreeDashboardPlugin(options: SpreeDashboardPluginOptions = {}): PluginOption[] {+ return [dashboardTailwindSourcePlugin(options), tailwindcss()]+}++function dashboardTailwindSourcePlugin(options: SpreeDashboardPluginOptions): Plugin {+ const pluginPackages = options.plugins ?? []+ const cssEntry = options.cssEntry ?? './src/styles.css'++ // Resolution roots from this file's location. Wherever+ // `@spree/dashboard-core` ends up on disk (workspace symlink, hoisted+ // npm install, pnpm `.pnpm/` directory), the sibling `@spree/*` packages+ // are reachable from here via Node module resolution.+ const fromHere = createRequire(import.meta.url)++ let resolvedSources: string[] = []+ let resolvedCssEntry = ''++ return {+ name: 'spree:dashboard-tailwind-source',+ enforce: 'pre',++ configResolved(config) {+ resolvedCssEntry = path.resolve(config.root, cssEntry).split(path.sep).join('/')++ const packagesToScan = ['@spree/dashboard-core', '@spree/dashboard-ui', ...pluginPackages]++ resolvedSources = packagesToScan+ .map((pkg) => resolvePackageSourceDir(pkg, fromHere))+ .filter((dir): dir is string => dir !== null)+ },++ transform(code, id) {+ const normalized = id.split('?')[0].replaceAll('\\', '/')+ if (normalized !== resolvedCssEntry) return null++ const directives = resolvedSources.map((dir) => `@source '${dir}';`).join('\n')++ return {+ code: `${code}\n\n/* injected by @spree/dashboard-core/vite */\n${directives}\n`,+ map: null,+ }+ },+ }+}++/**+ * Resolve `<package>/src` on disk. Resolves the package's main entry point+ * (defined by its `exports` map or `main` field) and walks upwards looking+ * for `package.json` to find the package root. Avoids requiring+ * `<pkg>/package.json` to be in the package's `exports` map — many packages,+ * including ours, don't list it there.+ */+function resolvePackageSourceDir(pkg: string, require: NodeJS.Require): string | null {+ try {+ const entryPath = require.resolve(pkg)+ const entryFile = entryPath.startsWith('file:') ? fileURLToPath(entryPath) : entryPath+ const packageRoot = findPackageRoot(entryFile)+ if (!packageRoot) return null+ return path.join(packageRoot, 'src')+ } catch {+ console.warn(+ `[@spree/dashboard-core/vite] Could not resolve '${pkg}'. ` ++ `Tailwind classes from this package won't be generated. ` ++ `Make sure the package is installed.`,+ )+ return null+ }+}++function findPackageRoot(fromFile: string): string | null {+ let current = path.dirname(fromFile)+ const { root } = path.parse(current)+ while (current !== root) {+ if (fs.existsSync(path.join(current, 'package.json'))) return current+ current = path.dirname(current)+ }+ return null+}diff --git a/packages/dashboard/README.md b/packages/dashboard/README.mdindex 7701d7c38f..8a43d0abd2 100644--- a/packages/dashboard/README.md+++ b/packages/dashboard/README.md@@ -21,6 +21,46 @@ Part of the three-package dashboard stack — see [`packages/README.md`](../READ| Notifications | [Sonner](https://sonner.emilkowal.ski/) || Lint & format | [Biome](https://biomejs.dev/) |+## Host integration++Host apps consume the dashboard by installing all three packages and wiring our Vite plugin into their build:++```ts+// host vite.config.ts+import { spreeDashboardPlugin } from '@spree/dashboard/vite'+import { TanStackRouterVite } from '@tanstack/router-plugin/vite'+import react from '@vitejs/plugin-react'+import { defineConfig } from 'vite'++export default defineConfig({+ plugins: [+ spreeDashboardPlugin({+ plugins: [+ '@my-store/orders-dashboard-plugin',+ '@my-store/wishlists-dashboard-plugin',+ ],+ }),+ TanStackRouterVite(),+ react(),+ ],+})+```++```css+/* host src/styles.css */+@import "@spree/dashboard/styles.css";+```++```ts+// host src/main.tsx+import '@my-store/orders-dashboard-plugin' // side-effect: defineDashboardPlugin()+import '@my-store/wishlists-dashboard-plugin'+import './styles.css'+// … mount the app+```++The Vite plugin bundles `@tailwindcss/vite` and injects `@source` directives for every Spree dashboard package and every host-named plugin, so hosts don't configure Tailwind directly. `@spree/dashboard/vite` is a thin re-export of [`@spree/dashboard-core/vite`](../dashboard-core/README.md#vite-integration) — that's where the plugin lives and where the full options reference (custom dashboards, plugin authoring, `cssEntry`, etc.) is documented.+## Getting startedThe admin needs a running Spree backend exposing the Admin API. The simplest setup:diff --git a/packages/dashboard/package.json b/packages/dashboard/package.jsonindex c1a97cf038..2aa3f173c8 100644--- a/packages/dashboard/package.json+++ b/packages/dashboard/package.json@@ -4,6 +4,14 @@"license": "MIT","version": "0.0.0","type": "module",+ "exports": {+ "./styles.css": "./src/styles.css",+ "./vite": "./src/vite/index.ts"+ },+ "files": [+ "src",+ "README.md"+ ],"scripts": {"dev": "vite","build": "tsc -b && vite build",@@ -60,7 +68,6 @@},"devDependencies": {"@playwright/test": "^1.59.1",- "@tailwindcss/vite": "^4.2.4","@tanstack/router-plugin": "^1.167.35","@types/node": "^25.6.0","@types/react": "^19.2.14",diff --git a/packages/dashboard/src/main.tsx b/packages/dashboard/src/main.tsxindex 472bd191a6..b2fa681968 100644--- a/packages/dashboard/src/main.tsx+++ b/packages/dashboard/src/main.tsx@@ -13,7 +13,7 @@ import '@/nav/settings'import { AuthProvider, PermissionProvider, queryClient } from '@spree/dashboard-core'import { ThemeProvider } from '@spree/dashboard-ui'import { router } from '@/router'-import '@spree/dashboard-ui/styles.css'+import '@/styles.css'createRoot(document.getElementById('root')!).render(<StrictMode>diff --git a/packages/dashboard/src/styles.css b/packages/dashboard/src/styles.cssnew file mode 100644index 0000000000..de2a71071e--- /dev/null+++ b/packages/dashboard/src/styles.css@@ -0,0 +1,25 @@+/* Dashboard CSS entry.+ *+ * Pulls in the design system stylesheet from `@spree/dashboard-ui` (which+ * provides Tailwind v4 layers, design tokens, base styles, and `@source`+ * directives for its own components).+ *+ * `@source` directives for `@spree/dashboard-core` and any installed dashboard+ * plugins are appended to this file at build time by `spreeDashboardPlugin`+ * from `@spree/dashboard/vite`. Resolution goes through Node module+ * resolution, so paths are correct under any package layout (workspace+ * symlinks, npm tarballs, pnpm's `.pnpm/` hoisting).+ *+ * Host apps:+ *+ * // index.css+ * @import "@spree/dashboard/styles.css";+ *+ * // vite.config.ts+ * plugins: [spreeDashboardPlugin({ plugins: ['@my-store/orders'] })]+ *+ * The Vite plugin bundles `@tailwindcss/vite` internally, so host apps must+ * NOT register `tailwindcss()` separately.+ */++@import "@spree/dashboard-ui/styles.css";diff --git a/packages/dashboard/src/vite/index.ts b/packages/dashboard/src/vite/index.tsnew file mode 100644index 0000000000..bfcdd07396--- /dev/null+++ b/packages/dashboard/src/vite/index.ts@@ -0,0 +1,8 @@+/* Re-export of `@spree/dashboard-core/vite` so host apps that already depend+ * on the `@spree/dashboard` umbrella package can keep importing from+ * `@spree/dashboard/vite`. The plugin's implementation lives in+ * `@spree/dashboard-core` so custom dashboards built on `dashboard-core` ++ * `dashboard-ui` (without the `dashboard` app shell) can use it too.+ */+export type { SpreeDashboardPluginOptions } from '@spree/dashboard-core/vite'+export { spreeDashboardPlugin } from '@spree/dashboard-core/vite'diff --git a/packages/dashboard/vite.config.ts b/packages/dashboard/vite.config.tsindex 3ddb19146a..cf04948c8a 100644--- a/packages/dashboard/vite.config.ts+++ b/packages/dashboard/vite.config.ts@@ -1,11 +1,14 @@import path from 'node:path'-import tailwindcss from '@tailwindcss/vite'+import { spreeDashboardPlugin } from '@spree/dashboard-core/vite'import { TanStackRouterVite } from '@tanstack/router-plugin/vite'import react from '@vitejs/plugin-react'import { defineConfig } from 'vite'export default defineConfig({- plugins: [TanStackRouterVite(), react(), tailwindcss()],+ // The plugin bundles `@tailwindcss/vite`, so we don't register it separately.+ // `cssEntry` defaults to `./src/styles.css`, which matches our entry — pass+ // it here only as a hint for readers of this config.+ plugins: [spreeDashboardPlugin({ cssEntry: './src/styles.css' }), TanStackRouterVite(), react()],resolve: {alias: {'@': path.resolve(__dirname, './src'),diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 52134ca25a..91cec18817 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -258,9 +258,6 @@ importers:'@playwright/test':specifier: ^1.59.1version: 1.59.1- '@tailwindcss/vite':- specifier: ^4.2.4- version: 4.2.4([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))'@tanstack/router-plugin':specifier: ^1.167.35version: 1.167.35(@tanstack/[email protected]([email protected]([email protected]))([email protected]))([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))@@ -309,6 +306,9 @@ importers:'@spree/dashboard-ui':specifier: workspace:^version: link:../dashboard-ui+ '@tailwindcss/vite':+ specifier: ^4.2.4+ version: 4.2.4([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))'@tanstack/react-hotkeys':specifier: ^0.10.0@@ -3025,10 +3025,6 @@ packages:resolution: {integrity: sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==}engines: {node: '>=8'}- resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}- hasBin: true-resolution: {integrity: sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==}hasBin: true@@ -5349,7 +5345,7 @@ snapshots:dependencies:'@jridgewell/remapping': 2.3.5enhanced-resolve: 5.21.0- jiti: 2.6.1+ jiti: 2.7.0lightningcss: 1.32.0magic-string: 0.30.21source-map-js: 1.2.1@@ -6671,8 +6667,6 @@ snapshots:html-escaper: 2.0.2istanbul-lib-report: 3.0.1- [email protected]: {}-