@mantajs/dashboard 0.1.14 → 0.1.16

package/README.md

@@ -205,6 +205,92 @@ import type { MenuConfig, MenuItem, MenuNestedItem } from "@mantajs/dashboard/vi
 
 When no `menu.config.ts` is found, the dashboard falls back to its built-in sidebar menu.
 
+### Menu, Nested Routes, and Modules: How They Interact
+
+Understanding how the sidebar menu is built is critical to avoid duplicate or missing entries. There are **three sources** that can add items to the sidebar:
+
+1. **Your `menu.config.tsx`** — the custom menu you define
+2. **Route configs with `nested`** — pages that declare `nested: "/parent"` in `defineRouteConfig()`
+3. **Plugin modules** — modules like `@medusajs/draft-order` that register their own routes and menu entries
+
+#### How `nested` works
+
+When a route page exports a config with `nested`, Medusa **automatically injects** it as a sub-item under the specified parent in the sidebar:
+
+```tsx
+// src/admin/routes/draft-orders/page.tsx
+export const config = defineRouteConfig({
+  label: "Drafts",
+  nested: "/orders",   // ← auto-injected under Orders in the sidebar
+})
+```
+
+This happens **regardless** of your `menu.config.tsx`. Even if you define a custom menu, any route with `nested` will still be injected as a child of its parent entry.
+
+**To prevent a route from appearing in the sidebar**, remove the `nested` property:
+
+```tsx
+export const config = defineRouteConfig({
+  label: "Drafts Test",
+  // no `nested` → not auto-injected in the menu
+})
+```
+
+The page remains accessible via its URL (`/app/draft-orders`) but won't appear in the sidebar unless you explicitly add it to your menu config.
+
+#### Controlling sub-items via `menu.config.tsx`
+
+If you want full control over which sub-items appear under a menu entry, define them explicitly in `items`:
+
+```tsx
+{
+  icon: <ShoppingCart />,
+  label: "orders.domain",
+  useTranslation: true,
+  to: "/orders",
+  items: [
+    { label: "Draft Orders", to: "/draft-orders" },
+  ],
+}
+```
+
+**Important:** Nested routes (`nested: "/orders"`) are still injected even if you define `items` manually. To avoid duplicates, either:
+- Remove `nested` from the route config, **or**
+- Don't list the route in `items` (let `nested` handle it)
+
+Never do both — you'll get a duplicate entry.
+
+#### Plugin modules and the Extensions section
+
+Medusa plugin modules (e.g., `@medusajs/draft-order`) register their own sidebar entries. By default, these appear in the **Extensions** section at the bottom of the sidebar.
+
+When you include a module's route in your `menu.config.tsx`, the module's entry is **absorbed** into your custom menu and no longer appears separately in Extensions:
+
+```tsx
+// Including /draft-orders in the custom menu prevents it from
+// appearing again under Extensions
+{
+  icon: <ShoppingCart />,
+  label: "Orders",
+  to: "/orders",
+  items: [
+    { label: "Draft Orders", to: "/draft-orders" },  // ← module route
+  ],
+}
+```
+
+If you **don't** include a module's route in your menu config, it will appear in the Extensions section as usual.
+
+#### Summary
+
+| Scenario | Result |
+|----------|--------|
+| Route has `nested: "/orders"` | Auto-injected under Orders in sidebar |
+| Route has no `nested` | Not in sidebar (unless in `menu.config.tsx`) |
+| Module route listed in `menu.config.tsx` | Appears in your menu, not in Extensions |
+| Module route **not** in `menu.config.tsx` | Appears in Extensions section |
+| Route has `nested` **and** listed in `items` | Duplicate entry (avoid this!) |
+
 ## Exports
 
 | Import | Description |

package/dist/vite-plugin/index.js

@@ -86,9 +86,30 @@ function getComponentName(filePath) {
   }
   return baseName;
 }
+function findDashboardSrc() {
+  const cwd = process.cwd();
+  const candidates = [
+    import_path.default.join(cwd, "node_modules", "@medusajs", "dashboard", "src"),
+    import_path.default.join(cwd, "node_modules", "@mantajs", "dashboard", "src"),
+    import_path.default.join(cwd, ".yalc", "@mantajs", "dashboard", "src")
+  ];
+  for (const dir of candidates) {
+    if (import_fs.default.existsSync(dir)) return dir;
+  }
+  return null;
+}
 function customDashboardPlugin() {
   const componentsDir = import_path.default.resolve(process.cwd(), "src/admin/components");
   const overridesByName = /* @__PURE__ */ new Map();
+  const appliedOverrides = /* @__PURE__ */ new Set();
+  const knownDashboardComponents = /* @__PURE__ */ new Set();
+  const dashboardSrc = findDashboardSrc();
+  if (dashboardSrc) {
+    for (const f of collectComponentFiles(dashboardSrc)) {
+      const cName = getComponentName(f);
+      if (cName) knownDashboardComponents.add(cName);
+    }
+  }
   if (import_fs.default.existsSync(componentsDir)) {
     const collectedFiles = collectComponentFiles(componentsDir).sort();
     for (const fullPath of collectedFiles) {
@@ -105,8 +126,15 @@ function customDashboardPlugin() {
     }
   }
   const hasOverrides = overridesByName.size > 0;
-  if (hasOverrides && process.env.NODE_ENV === "development") {
-    console.log("[custom-dashboard] overrides:", [...overridesByName.keys()]);
+  if (process.env.NODE_ENV === "development") {
+    if (hasOverrides) {
+      console.log("[custom-dashboard] overrides:", [...overridesByName.keys()]);
+    }
+    if (knownDashboardComponents.size > 0) {
+      console.log(
+        `[custom-dashboard] Scanned ${knownDashboardComponents.size} dashboard components for override matching`
+      );
+    }
   }
   return {
     name: "custom-dashboard",
@@ -115,67 +143,126 @@ function customDashboardPlugin() {
       config.optimizeDeps = config.optimizeDeps || {};
       config.optimizeDeps.exclude = config.optimizeDeps.exclude || [];
       config.optimizeDeps.exclude.push(MENU_VIRTUAL_ID);
-      if (hasOverrides) {
-        config.optimizeDeps.esbuildOptions = config.optimizeDeps.esbuildOptions || {};
-        config.optimizeDeps.esbuildOptions.plugins = config.optimizeDeps.esbuildOptions.plugins || [];
-        const overrides = overridesByName;
-        config.optimizeDeps.esbuildOptions.plugins.push({
-          name: "dashboard-component-overrides",
-          setup(build) {
-            build.onLoad({ filter: /app\.(mjs|js)$/ }, (args) => {
-              const normalized = args.path.replace(/\\/g, "/");
-              if (!normalized.includes("/dashboard/dist/")) return void 0;
-              const srcEntry = normalized.replace(/\/dist\/app\.(mjs|js)$/, "/src/app.tsx");
+      config.optimizeDeps.esbuildOptions = config.optimizeDeps.esbuildOptions || {};
+      config.optimizeDeps.esbuildOptions.plugins = config.optimizeDeps.esbuildOptions.plugins || [];
+      const overrides = overridesByName;
+      config.optimizeDeps.esbuildOptions.plugins.push({
+        name: "dashboard-component-overrides",
+        setup(build) {
+          build.onLoad({ filter: /app\.(mjs|js)$/ }, (args) => {
+            if (overrides.size === 0) return void 0;
+            const normalized = args.path.replace(/\\/g, "/");
+            if (!normalized.includes("/dashboard/dist/")) return void 0;
+            const srcEntry = normalized.replace(/\/dist\/app\.(mjs|js)$/, "/src/app.tsx");
+            let contents;
+            try {
+              contents = import_fs.default.readFileSync(srcEntry, "utf-8");
+            } catch {
+              return void 0;
+            }
+            if (process.env.NODE_ENV === "development") {
+              console.log(
+                `[custom-dashboard] Redirecting entry: ${args.path} \u2192 ${srcEntry}`
+              );
+            }
+            return {
+              contents,
+              loader: "tsx",
+              resolveDir: import_path.default.dirname(srcEntry)
+            };
+          });
+          build.onLoad({ filter: /\.(tsx?|jsx?)$/ }, (args) => {
+            if (overrides.size === 0) return void 0;
+            const normalized = args.path.replace(/\\/g, "/");
+            if (!normalized.includes("/dashboard/src/")) return void 0;
+            const fileName = import_path.default.basename(args.path);
+            if (fileName.startsWith("index.")) return void 0;
+            const componentName = getComponentName(args.path);
+            if (componentName && overrides.has(componentName)) {
+              const overridePath = overrides.get(componentName);
+              const ext = import_path.default.extname(overridePath).slice(1);
+              const loader = VALID_LOADERS[ext] || "tsx";
               let contents;
               try {
-                contents = import_fs.default.readFileSync(srcEntry, "utf-8");
+                contents = import_fs.default.readFileSync(overridePath, "utf-8");
               } catch {
                 return void 0;
               }
+              appliedOverrides.add(componentName);
               if (process.env.NODE_ENV === "development") {
                 console.log(
-                  `[custom-dashboard] Redirecting entry: ${args.path} \u2192 ${srcEntry}`
+                  `[custom-dashboard] Override: ${componentName} \u2192 ${overridePath}`
                 );
               }
               return {
                 contents,
-                loader: "tsx",
-                resolveDir: import_path.default.dirname(srcEntry)
+                loader,
+                resolveDir: import_path.default.dirname(overridePath)
               };
-            });
-            build.onLoad({ filter: /\.(tsx?|jsx?)$/ }, (args) => {
-              const normalized = args.path.replace(/\\/g, "/");
-              if (!normalized.includes("/dashboard/src/")) return void 0;
-              const fileName = import_path.default.basename(args.path);
-              if (fileName.startsWith("index.")) return void 0;
-              const componentName = getComponentName(args.path);
-              if (componentName && overrides.has(componentName)) {
-                const overridePath = overrides.get(componentName);
-                const ext = import_path.default.extname(overridePath).slice(1);
-                const loader = VALID_LOADERS[ext] || "tsx";
-                let contents;
-                try {
-                  contents = import_fs.default.readFileSync(overridePath, "utf-8");
-                } catch {
-                  return void 0;
-                }
-                if (process.env.NODE_ENV === "development") {
-                  console.log(
-                    `[custom-dashboard] Override: ${componentName} \u2192 ${overridePath}`
-                  );
-                }
-                return {
-                  contents,
-                  loader,
-                  resolveDir: import_path.default.dirname(overridePath)
-                };
-              }
-              return void 0;
-            });
+            }
+            return void 0;
+          });
+        }
+      });
+      config.optimizeDeps.force = true;
+    },
+    configureServer(server) {
+      if (!import_fs.default.existsSync(componentsDir)) return;
+      let debounceTimer = null;
+      const extractName = (file) => {
+        const normalized = file.replace(/\\/g, "/");
+        if (!normalized.startsWith(componentsDir.replace(/\\/g, "/"))) return null;
+        const ext = import_path.default.extname(file);
+        if (!COMPONENT_EXT_SET.has(ext)) return null;
+        const fileName = import_path.default.basename(file);
+        const name = fileName.replace(/\.(tsx?|jsx?|mts|mjs)$/, "");
+        if (!name || name === "index") return null;
+        return name;
+      };
+      const triggerRestart = (name, reason) => {
+        if (debounceTimer) clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+          const newOverrides = /* @__PURE__ */ new Map();
+          const collectedFiles = collectComponentFiles(componentsDir).sort();
+          for (const fullPath of collectedFiles) {
+            const fn = import_path.default.basename(fullPath);
+            const n = fn.replace(/\.(tsx?|jsx?|mts|mjs)$/, "");
+            if (n && n !== "index") {
+              newOverrides.set(n, fullPath);
+            }
           }
-        });
-        config.optimizeDeps.force = true;
-      }
+          overridesByName.clear();
+          for (const [k, v] of newOverrides) overridesByName.set(k, v);
+          console.log(
+            `[custom-dashboard] Override "${name}" ${reason} \u2192 restarting Vite...`
+          );
+          console.log(
+            `[custom-dashboard] overrides:`,
+            [...overridesByName.keys()]
+          );
+          server.restart();
+        }, 300);
+      };
+      server.watcher.add(componentsDir);
+      server.watcher.on("add", (file) => {
+        const name = extractName(file);
+        if (name && knownDashboardComponents.has(name)) {
+          triggerRestart(name, "created");
+        }
+      });
+      server.watcher.on("change", (file) => {
+        const name = extractName(file);
+        if (name && appliedOverrides.has(name)) {
+          triggerRestart(name, "modified");
+        }
+      });
+      server.watcher.on("unlink", (file) => {
+        const name = extractName(file);
+        if (name && appliedOverrides.has(name)) {
+          appliedOverrides.delete(name);
+          triggerRestart(name, "deleted");
+        }
+      });
     },
     resolveId(source) {
       if (source === MENU_VIRTUAL_ID) return MENU_RESOLVED_ID;

package/dist/vite-plugin/index.mjs

@@ -51,9 +51,30 @@ function getComponentName(filePath) {
   }
   return baseName;
 }
+function findDashboardSrc() {
+  const cwd = process.cwd();
+  const candidates = [
+    path.join(cwd, "node_modules", "@medusajs", "dashboard", "src"),
+    path.join(cwd, "node_modules", "@mantajs", "dashboard", "src"),
+    path.join(cwd, ".yalc", "@mantajs", "dashboard", "src")
+  ];
+  for (const dir of candidates) {
+    if (fs.existsSync(dir)) return dir;
+  }
+  return null;
+}
 function customDashboardPlugin() {
   const componentsDir = path.resolve(process.cwd(), "src/admin/components");
   const overridesByName = /* @__PURE__ */ new Map();
+  const appliedOverrides = /* @__PURE__ */ new Set();
+  const knownDashboardComponents = /* @__PURE__ */ new Set();
+  const dashboardSrc = findDashboardSrc();
+  if (dashboardSrc) {
+    for (const f of collectComponentFiles(dashboardSrc)) {
+      const cName = getComponentName(f);
+      if (cName) knownDashboardComponents.add(cName);
+    }
+  }
   if (fs.existsSync(componentsDir)) {
     const collectedFiles = collectComponentFiles(componentsDir).sort();
     for (const fullPath of collectedFiles) {
@@ -70,8 +91,15 @@ function customDashboardPlugin() {
     }
   }
   const hasOverrides = overridesByName.size > 0;
-  if (hasOverrides && process.env.NODE_ENV === "development") {
-    console.log("[custom-dashboard] overrides:", [...overridesByName.keys()]);
+  if (process.env.NODE_ENV === "development") {
+    if (hasOverrides) {
+      console.log("[custom-dashboard] overrides:", [...overridesByName.keys()]);
+    }
+    if (knownDashboardComponents.size > 0) {
+      console.log(
+        `[custom-dashboard] Scanned ${knownDashboardComponents.size} dashboard components for override matching`
+      );
+    }
   }
   return {
     name: "custom-dashboard",
@@ -80,67 +108,126 @@ function customDashboardPlugin() {
       config.optimizeDeps = config.optimizeDeps || {};
       config.optimizeDeps.exclude = config.optimizeDeps.exclude || [];
       config.optimizeDeps.exclude.push(MENU_VIRTUAL_ID);
-      if (hasOverrides) {
-        config.optimizeDeps.esbuildOptions = config.optimizeDeps.esbuildOptions || {};
-        config.optimizeDeps.esbuildOptions.plugins = config.optimizeDeps.esbuildOptions.plugins || [];
-        const overrides = overridesByName;
-        config.optimizeDeps.esbuildOptions.plugins.push({
-          name: "dashboard-component-overrides",
-          setup(build) {
-            build.onLoad({ filter: /app\.(mjs|js)$/ }, (args) => {
-              const normalized = args.path.replace(/\\/g, "/");
-              if (!normalized.includes("/dashboard/dist/")) return void 0;
-              const srcEntry = normalized.replace(/\/dist\/app\.(mjs|js)$/, "/src/app.tsx");
+      config.optimizeDeps.esbuildOptions = config.optimizeDeps.esbuildOptions || {};
+      config.optimizeDeps.esbuildOptions.plugins = config.optimizeDeps.esbuildOptions.plugins || [];
+      const overrides = overridesByName;
+      config.optimizeDeps.esbuildOptions.plugins.push({
+        name: "dashboard-component-overrides",
+        setup(build) {
+          build.onLoad({ filter: /app\.(mjs|js)$/ }, (args) => {
+            if (overrides.size === 0) return void 0;
+            const normalized = args.path.replace(/\\/g, "/");
+            if (!normalized.includes("/dashboard/dist/")) return void 0;
+            const srcEntry = normalized.replace(/\/dist\/app\.(mjs|js)$/, "/src/app.tsx");
+            let contents;
+            try {
+              contents = fs.readFileSync(srcEntry, "utf-8");
+            } catch {
+              return void 0;
+            }
+            if (process.env.NODE_ENV === "development") {
+              console.log(
+                `[custom-dashboard] Redirecting entry: ${args.path} \u2192 ${srcEntry}`
+              );
+            }
+            return {
+              contents,
+              loader: "tsx",
+              resolveDir: path.dirname(srcEntry)
+            };
+          });
+          build.onLoad({ filter: /\.(tsx?|jsx?)$/ }, (args) => {
+            if (overrides.size === 0) return void 0;
+            const normalized = args.path.replace(/\\/g, "/");
+            if (!normalized.includes("/dashboard/src/")) return void 0;
+            const fileName = path.basename(args.path);
+            if (fileName.startsWith("index.")) return void 0;
+            const componentName = getComponentName(args.path);
+            if (componentName && overrides.has(componentName)) {
+              const overridePath = overrides.get(componentName);
+              const ext = path.extname(overridePath).slice(1);
+              const loader = VALID_LOADERS[ext] || "tsx";
               let contents;
               try {
-                contents = fs.readFileSync(srcEntry, "utf-8");
+                contents = fs.readFileSync(overridePath, "utf-8");
               } catch {
                 return void 0;
               }
+              appliedOverrides.add(componentName);
               if (process.env.NODE_ENV === "development") {
                 console.log(
-                  `[custom-dashboard] Redirecting entry: ${args.path} \u2192 ${srcEntry}`
+                  `[custom-dashboard] Override: ${componentName} \u2192 ${overridePath}`
                 );
               }
               return {
                 contents,
-                loader: "tsx",
-                resolveDir: path.dirname(srcEntry)
+                loader,
+                resolveDir: path.dirname(overridePath)
               };
-            });
-            build.onLoad({ filter: /\.(tsx?|jsx?)$/ }, (args) => {
-              const normalized = args.path.replace(/\\/g, "/");
-              if (!normalized.includes("/dashboard/src/")) return void 0;
-              const fileName = path.basename(args.path);
-              if (fileName.startsWith("index.")) return void 0;
-              const componentName = getComponentName(args.path);
-              if (componentName && overrides.has(componentName)) {
-                const overridePath = overrides.get(componentName);
-                const ext = path.extname(overridePath).slice(1);
-                const loader = VALID_LOADERS[ext] || "tsx";
-                let contents;
-                try {
-                  contents = fs.readFileSync(overridePath, "utf-8");
-                } catch {
-                  return void 0;
-                }
-                if (process.env.NODE_ENV === "development") {
-                  console.log(
-                    `[custom-dashboard] Override: ${componentName} \u2192 ${overridePath}`
-                  );
-                }
-                return {
-                  contents,
-                  loader,
-                  resolveDir: path.dirname(overridePath)
-                };
-              }
-              return void 0;
-            });
+            }
+            return void 0;
+          });
+        }
+      });
+      config.optimizeDeps.force = true;
+    },
+    configureServer(server) {
+      if (!fs.existsSync(componentsDir)) return;
+      let debounceTimer = null;
+      const extractName = (file) => {
+        const normalized = file.replace(/\\/g, "/");
+        if (!normalized.startsWith(componentsDir.replace(/\\/g, "/"))) return null;
+        const ext = path.extname(file);
+        if (!COMPONENT_EXT_SET.has(ext)) return null;
+        const fileName = path.basename(file);
+        const name = fileName.replace(/\.(tsx?|jsx?|mts|mjs)$/, "");
+        if (!name || name === "index") return null;
+        return name;
+      };
+      const triggerRestart = (name, reason) => {
+        if (debounceTimer) clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+          const newOverrides = /* @__PURE__ */ new Map();
+          const collectedFiles = collectComponentFiles(componentsDir).sort();
+          for (const fullPath of collectedFiles) {
+            const fn = path.basename(fullPath);
+            const n = fn.replace(/\.(tsx?|jsx?|mts|mjs)$/, "");
+            if (n && n !== "index") {
+              newOverrides.set(n, fullPath);
+            }
           }
-        });
-        config.optimizeDeps.force = true;
-      }
+          overridesByName.clear();
+          for (const [k, v] of newOverrides) overridesByName.set(k, v);
+          console.log(
+            `[custom-dashboard] Override "${name}" ${reason} \u2192 restarting Vite...`
+          );
+          console.log(
+            `[custom-dashboard] overrides:`,
+            [...overridesByName.keys()]
+          );
+          server.restart();
+        }, 300);
+      };
+      server.watcher.add(componentsDir);
+      server.watcher.on("add", (file) => {
+        const name = extractName(file);
+        if (name && knownDashboardComponents.has(name)) {
+          triggerRestart(name, "created");
+        }
+      });
+      server.watcher.on("change", (file) => {
+        const name = extractName(file);
+        if (name && appliedOverrides.has(name)) {
+          triggerRestart(name, "modified");
+        }
+      });
+      server.watcher.on("unlink", (file) => {
+        const name = extractName(file);
+        if (name && appliedOverrides.has(name)) {
+          appliedOverrides.delete(name);
+          triggerRestart(name, "deleted");
+        }
+      });
     },
     resolveId(source) {
       if (source === MENU_VIRTUAL_ID) return MENU_RESOLVED_ID;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantajs/dashboard",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "B2B Admin Dashboard for Medusa - Fork of @medusajs/dashboard",
   "license": "MIT",
   "author": {

package/src/vite-plugin/index.ts

@@ -1,4 +1,4 @@
-import { Plugin } from "vite"
+import { Plugin, ViteDevServer } from "vite"
 import path from "path"
 import fs from "fs"
 
@@ -68,6 +68,23 @@ function getComponentName(filePath: string): string | null {
   return baseName
 }
 
+/**
+ * Find the dashboard source directory by checking known install paths.
+ * Works with yarn resolutions, direct installs, and yalc links.
+ */
+function findDashboardSrc(): string | null {
+  const cwd = process.cwd()
+  const candidates = [
+    path.join(cwd, "node_modules", "@medusajs", "dashboard", "src"),
+    path.join(cwd, "node_modules", "@mantajs", "dashboard", "src"),
+    path.join(cwd, ".yalc", "@mantajs", "dashboard", "src"),
+  ]
+  for (const dir of candidates) {
+    if (fs.existsSync(dir)) return dir
+  }
+  return null
+}
+
 /**
  * Unified Vite plugin for @mantajs/dashboard.
  *
@@ -80,6 +97,23 @@ export function customDashboardPlugin(): Plugin {
   const componentsDir = path.resolve(process.cwd(), "src/admin/components")
   const overridesByName = new Map<string, string>()
 
+  // Track which overrides were actually matched during esbuild pre-bundling.
+  // Only these are real overrides — the rest are regular project components
+  // that happen to live in the same directory.
+  const appliedOverrides = new Set<string>()
+
+  // Scan dashboard source at startup to know all possible override targets.
+  // This lets the file watcher decide if a newly created file could be an
+  // override, without maintaining any hardcoded list.
+  const knownDashboardComponents = new Set<string>()
+  const dashboardSrc = findDashboardSrc()
+  if (dashboardSrc) {
+    for (const f of collectComponentFiles(dashboardSrc)) {
+      const cName = getComponentName(f)
+      if (cName) knownDashboardComponents.add(cName)
+    }
+  }
+
   if (fs.existsSync(componentsDir)) {
     const collectedFiles = collectComponentFiles(componentsDir).sort()
     for (const fullPath of collectedFiles) {
@@ -98,8 +132,15 @@ export function customDashboardPlugin(): Plugin {
 
   const hasOverrides = overridesByName.size > 0
 
-  if (hasOverrides && process.env.NODE_ENV === "development") {
-    console.log("[custom-dashboard] overrides:", [...overridesByName.keys()])
+  if (process.env.NODE_ENV === "development") {
+    if (hasOverrides) {
+      console.log("[custom-dashboard] overrides:", [...overridesByName.keys()])
+    }
+    if (knownDashboardComponents.size > 0) {
+      console.log(
+        `[custom-dashboard] Scanned ${knownDashboardComponents.size} dashboard components for override matching`
+      )
+    }
   }
 
   return {
@@ -112,89 +153,169 @@ export function customDashboardPlugin(): Plugin {
       config.optimizeDeps.exclude = config.optimizeDeps.exclude || []
       config.optimizeDeps.exclude.push(MENU_VIRTUAL_ID)
 
-      if (hasOverrides) {
-        // Strategy: the package.json points to dist/app.mjs (so the browser
-        // gets a working pre-bundled chunk — no blank page).  But during
-        // esbuild pre-bundling we redirect the dist entry to the source TSX
-        // via onLoad, so esbuild follows individual imports and we can swap
-        // component files with the user's overrides.
-        config.optimizeDeps.esbuildOptions = config.optimizeDeps.esbuildOptions || {}
-        config.optimizeDeps.esbuildOptions.plugins =
-          config.optimizeDeps.esbuildOptions.plugins || []
-
-        const overrides = overridesByName
-        config.optimizeDeps.esbuildOptions.plugins.push({
-          name: "dashboard-component-overrides",
-          setup(build) {
-            // 1. Redirect the dist entry to source so esbuild processes
-            //    individual TSX files instead of one big pre-built bundle.
-            build.onLoad({ filter: /app\.(mjs|js)$/ }, (args) => {
-              const normalized = args.path.replace(/\\/g, "/")
-              if (!normalized.includes("/dashboard/dist/")) return undefined
-
-              const srcEntry = normalized
-                .replace(/\/dist\/app\.(mjs|js)$/, "/src/app.tsx")
+      // Always set up the esbuild override plugin — even if there are no
+      // overrides yet, the configureServer watcher may add some at runtime
+      // and trigger a restart.
+      config.optimizeDeps.esbuildOptions = config.optimizeDeps.esbuildOptions || {}
+      config.optimizeDeps.esbuildOptions.plugins =
+        config.optimizeDeps.esbuildOptions.plugins || []
+
+      const overrides = overridesByName
+      config.optimizeDeps.esbuildOptions.plugins.push({
+        name: "dashboard-component-overrides",
+        setup(build) {
+          // 1. Redirect the dist entry to source so esbuild processes
+          //    individual TSX files instead of one big pre-built bundle.
+          build.onLoad({ filter: /app\.(mjs|js)$/ }, (args) => {
+            // Only activate when there are overrides
+            if (overrides.size === 0) return undefined
+
+            const normalized = args.path.replace(/\\/g, "/")
+            if (!normalized.includes("/dashboard/dist/")) return undefined
+
+            const srcEntry = normalized
+              .replace(/\/dist\/app\.(mjs|js)$/, "/src/app.tsx")
+
+            let contents: string
+            try {
+              contents = fs.readFileSync(srcEntry, "utf-8")
+            } catch {
+              return undefined
+            }
+
+            if (process.env.NODE_ENV === "development") {
+              console.log(
+                `[custom-dashboard] Redirecting entry: ${args.path} → ${srcEntry}`
+              )
+            }
+            return {
+              contents,
+              loader: "tsx",
+              resolveDir: path.dirname(srcEntry),
+            }
+          })
+
+          // 2. Intercept individual source files to swap with overrides.
+          build.onLoad({ filter: /\.(tsx?|jsx?)$/ }, (args) => {
+            if (overrides.size === 0) return undefined
+
+            const normalized = args.path.replace(/\\/g, "/")
+            if (!normalized.includes("/dashboard/src/")) return undefined
+
+            // Skip index/barrel files to preserve re-exports
+            const fileName = path.basename(args.path)
+            if (fileName.startsWith("index.")) return undefined
+
+            const componentName = getComponentName(args.path)
+            if (componentName && overrides.has(componentName)) {
+              const overridePath = overrides.get(componentName)!
+              const ext = path.extname(overridePath).slice(1)
+              const loader = VALID_LOADERS[ext] || "tsx"
 
               let contents: string
               try {
-                contents = fs.readFileSync(srcEntry, "utf-8")
+                contents = fs.readFileSync(overridePath, "utf-8")
               } catch {
                 return undefined
               }
 
+              // Track this as a real applied override
+              appliedOverrides.add(componentName)
+
               if (process.env.NODE_ENV === "development") {
                 console.log(
-                  `[custom-dashboard] Redirecting entry: ${args.path} → ${srcEntry}`
+                  `[custom-dashboard] Override: ${componentName} → ${overridePath}`
                 )
               }
               return {
                 contents,
-                loader: "tsx",
-                resolveDir: path.dirname(srcEntry),
-              }
-            })
-
-            // 2. Intercept individual source files to swap with overrides.
-            build.onLoad({ filter: /\.(tsx?|jsx?)$/ }, (args) => {
-              const normalized = args.path.replace(/\\/g, "/")
-              if (!normalized.includes("/dashboard/src/")) return undefined
-
-              // Skip index/barrel files to preserve re-exports
-              const fileName = path.basename(args.path)
-              if (fileName.startsWith("index.")) return undefined
-
-              const componentName = getComponentName(args.path)
-              if (componentName && overrides.has(componentName)) {
-                const overridePath = overrides.get(componentName)!
-                const ext = path.extname(overridePath).slice(1)
-                const loader = VALID_LOADERS[ext] || "tsx"
-
-                let contents: string
-                try {
-                  contents = fs.readFileSync(overridePath, "utf-8")
-                } catch {
-                  return undefined
-                }
-
-                if (process.env.NODE_ENV === "development") {
-                  console.log(
-                    `[custom-dashboard] Override: ${componentName} → ${overridePath}`
-                  )
-                }
-                return {
-                  contents,
-                  loader: loader as any,
-                  resolveDir: path.dirname(overridePath),
-                }
+                loader: loader as any,
+                resolveDir: path.dirname(overridePath),
               }
-              return undefined
-            })
-          },
-        })
+            }
+            return undefined
+          })
+        },
+      })
+
+      // Force re-optimisation so overrides are always applied
+      config.optimizeDeps.force = true
+    },
+
+    configureServer(server: ViteDevServer) {
+      if (!fs.existsSync(componentsDir)) return
 
-        // Force re-optimisation so overrides are always applied
-        config.optimizeDeps.force = true
+      let debounceTimer: ReturnType<typeof setTimeout> | null = null
+
+      /** Extract override-candidate name from a watched file, or null */
+      const extractName = (file: string): string | null => {
+        const normalized = file.replace(/\\/g, "/")
+        if (!normalized.startsWith(componentsDir.replace(/\\/g, "/"))) return null
+        const ext = path.extname(file)
+        if (!COMPONENT_EXT_SET.has(ext)) return null
+        const fileName = path.basename(file)
+        const name = fileName.replace(/\.(tsx?|jsx?|mts|mjs)$/, "")
+        if (!name || name === "index") return null
+        return name
       }
+
+      /** Re-collect overrides from disk and restart the dev server */
+      const triggerRestart = (name: string, reason: string) => {
+        if (debounceTimer) clearTimeout(debounceTimer)
+        debounceTimer = setTimeout(() => {
+          const newOverrides = new Map<string, string>()
+          const collectedFiles = collectComponentFiles(componentsDir).sort()
+          for (const fullPath of collectedFiles) {
+            const fn = path.basename(fullPath)
+            const n = fn.replace(/\.(tsx?|jsx?|mts|mjs)$/, "")
+            if (n && n !== "index") {
+              newOverrides.set(n, fullPath)
+            }
+          }
+
+          overridesByName.clear()
+          for (const [k, v] of newOverrides) overridesByName.set(k, v)
+
+          console.log(
+            `[custom-dashboard] Override "${name}" ${reason} → restarting Vite...`
+          )
+          console.log(
+            `[custom-dashboard] overrides:`,
+            [...overridesByName.keys()]
+          )
+
+          server.restart()
+        }, 300)
+      }
+
+      server.watcher.add(componentsDir)
+
+      // ADD: new file — restart only if its name matches a known dashboard
+      // component (i.e. it could be a new override)
+      server.watcher.on("add", (file: string) => {
+        const name = extractName(file)
+        if (name && knownDashboardComponents.has(name)) {
+          triggerRestart(name, "created")
+        }
+      })
+
+      // CHANGE: file modified — restart only if it's an active override
+      // (was matched by esbuild during pre-bundling)
+      server.watcher.on("change", (file: string) => {
+        const name = extractName(file)
+        if (name && appliedOverrides.has(name)) {
+          triggerRestart(name, "modified")
+        }
+      })
+
+      // UNLINK: file deleted — restart only if it was an active override
+      server.watcher.on("unlink", (file: string) => {
+        const name = extractName(file)
+        if (name && appliedOverrides.has(name)) {
+          appliedOverrides.delete(name)
+          triggerRestart(name, "deleted")
+        }
+      })
     },
 
     resolveId(source) {