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.

Introduce `@spree/dashboard-vite` plugin (#14114)

Damian Legawiec1a1a1b2cba74
diff --git a/packages/dashboard-core/README.md b/packages/dashboard-core/README.md
index 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 basics
Your 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.json
index 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.ts
new file mode 100644
index 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.md
index 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 started
The admin needs a running Spree backend exposing the Admin API. The simplest setup:
diff --git a/packages/dashboard/package.json b/packages/dashboard/package.json
index 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.tsx
index 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.css
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.yaml
index 52134ca25a..91cec18817 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -258,9 +258,6 @@ importers:
'@playwright/test':
specifier: ^1.59.1
version: 1.59.1
- '@tailwindcss/vite':
- specifier: ^4.2.4
'@tanstack/router-plugin':
specifier: ^1.167.35
@@ -309,6 +306,9 @@ importers:
'@spree/dashboard-ui':
specifier: workspace:^
version: link:../dashboard-ui
+ '@tailwindcss/vite':
+ specifier: ^4.2.4
'@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.5
enhanced-resolve: 5.21.0
- jiti: 2.6.1
+ jiti: 2.7.0
lightningcss: 1.32.0
magic-string: 0.30.21
source-map-js: 1.2.1
@@ -6671,8 +6667,6 @@ snapshots:
html-escaper: 2.0.2
istanbul-lib-report: 3.0.1
-