@mantajs/dashboard 0.1.15 → 0.1.17

package/README.md

@@ -112,6 +112,16 @@ const OrderActivitySection = () => {
 export default OrderActivitySection
 ```
 
+**Developer experience (HMR):**
+
+| Action | Behavior | Details |
+|--------|----------|---------|
+| **Modify** an override | **HMR** (Hot Module Replacement) | The component is swapped in-place — no page reload, no React state loss. Instant feedback. |
+| **Create** a new override | **Automatic full reload** (~2-3s) | The Vite server restarts to rebuild the pre-bundle, then the browser reloads automatically. No manual refresh needed. |
+| **Delete** an override | **Automatic full reload** (~2-3s) | Same as creation — the original dashboard component is restored automatically. |
+
+Under the hood, override files are kept as **separate Vite modules** (not inlined into the pre-bundled chunk). This allows React Fast Refresh to handle modifications via standard HMR. Creation and deletion require a server restart because the esbuild chunk structure changes.
+
 **Important notes:**
 
 - Override files are discovered **recursively** in `src/admin/components/` and all its subdirectories.
@@ -143,6 +153,44 @@ your-project/
 
 This uses Medusa's `@medusajs/admin-vite-plugin` to discover routes in `src/admin/routes/`, combined with a custom merge function that ensures backward compatibility.
 
+**Route page example:**
+
+```tsx
+// src/admin/routes/orders/page.tsx
+import { defineRouteConfig } from "@medusajs/admin-sdk"
+import { ShoppingCart } from "@medusajs/icons"
+import { Container, Heading } from "@medusajs/ui"
+
+const OrdersPage = () => {
+  return (
+    <Container>
+      <Heading level="h1">My Custom Orders Page</Heading>
+      {/* Your custom orders list */}
+    </Container>
+  )
+}
+
+export const config = defineRouteConfig({
+  label: "Orders",
+  icon: ShoppingCart,
+})
+
+export default OrdersPage
+```
+
+**Developer experience:**
+
+Route overrides use Medusa's standard admin extension system (`@medusajs/admin-vite-plugin`), which provides its own HMR. Modifying a route page triggers a standard Vite HMR update — the page refreshes instantly without a full reload.
+
+**Component overrides vs Route overrides — when to use which:**
+
+| Use case | Approach |
+|----------|----------|
+| Replace a **full page** (e.g., the orders list) | Route override (`src/admin/routes/orders/page.tsx`) |
+| Replace a **section** inside a page (e.g., the customer info block in order detail) | Component override (`src/admin/components/order-customer-section.tsx`) |
+| Add a **new page** that doesn't exist in the dashboard | Route override (`src/admin/routes/my-page/page.tsx`) |
+| Tweak a **reusable UI element** used across multiple pages | Component override |
+
 ### 3. Custom Menu Configuration
 
 Define your own sidebar menu by creating a `src/admin/menu.config.tsx` file:

package/dist/vite-plugin/index.d.mts

@@ -22,8 +22,23 @@ type MenuConfig = {
  *
  * Handles:
  * 1. Menu config virtual module (virtual:dashboard/menu-config)
- * 2. Component overrides — any file in src/admin/components/ overrides the
- *    dashboard component with the same name.
+ * 2. Component overrides — any file in src/admin/components/ whose name
+ *    matches a dashboard component replaces it at build time.
+ *
+ * HMR Architecture:
+ * - Override files are NOT inlined into the esbuild pre-bundled chunk.
+ *   Instead, the chunk contains `export * from "/@fs/path/to/override.tsx"`,
+ *   keeping the override as a **separate Vite module**.
+ * - Because the override is a separate module exporting React components,
+ *   @vitejs/plugin-react adds React Fast Refresh boundaries
+ *   (import.meta.hot.accept). This makes the module self-accepting for HMR.
+ * - On MODIFICATION: Vite detects the file change, transforms it, and sends
+ *   an HMR update. React Fast Refresh swaps the component — no page reload.
+ * - On CREATION or DELETION: The esbuild pre-bundle must be rebuilt (the
+ *   chunk structure changes). We restart Vite + send a full-reload to the
+ *   browser so it picks up the new chunks automatically.
+ * - The fs.watch is independent from Vite's internal watcher, so it
+ *   survives server.restart() calls without losing events.
  */
 declare function customDashboardPlugin(): Plugin;
 declare const menuConfigPlugin: typeof customDashboardPlugin;

package/dist/vite-plugin/index.d.ts

@@ -22,8 +22,23 @@ type MenuConfig = {
  *
  * Handles:
  * 1. Menu config virtual module (virtual:dashboard/menu-config)
- * 2. Component overrides — any file in src/admin/components/ overrides the
- *    dashboard component with the same name.
+ * 2. Component overrides — any file in src/admin/components/ whose name
+ *    matches a dashboard component replaces it at build time.
+ *
+ * HMR Architecture:
+ * - Override files are NOT inlined into the esbuild pre-bundled chunk.
+ *   Instead, the chunk contains `export * from "/@fs/path/to/override.tsx"`,
+ *   keeping the override as a **separate Vite module**.
+ * - Because the override is a separate module exporting React components,
+ *   @vitejs/plugin-react adds React Fast Refresh boundaries
+ *   (import.meta.hot.accept). This makes the module self-accepting for HMR.
+ * - On MODIFICATION: Vite detects the file change, transforms it, and sends
+ *   an HMR update. React Fast Refresh swaps the component — no page reload.
+ * - On CREATION or DELETION: The esbuild pre-bundle must be rebuilt (the
+ *   chunk structure changes). We restart Vite + send a full-reload to the
+ *   browser so it picks up the new chunks automatically.
+ * - The fs.watch is independent from Vite's internal watcher, so it
+ *   survives server.restart() calls without losing events.
  */
 declare function customDashboardPlugin(): Plugin;
 declare const menuConfigPlugin: typeof customDashboardPlugin;

package/dist/vite-plugin/index.js

@@ -38,16 +38,9 @@ var import_path = __toESM(require("path"));
 var import_fs = __toESM(require("fs"));
 var MENU_VIRTUAL_ID = "virtual:dashboard/menu-config";
 var MENU_RESOLVED_ID = "\0" + MENU_VIRTUAL_ID;
+var OVERRIDE_PREFIX = "__mantajs_override__:";
 var COMPONENT_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js", ".mts", ".mjs"];
 var COMPONENT_EXT_SET = new Set(COMPONENT_EXTENSIONS);
-var VALID_LOADERS = {
-  tsx: "tsx",
-  ts: "ts",
-  jsx: "jsx",
-  js: "js",
-  mts: "ts",
-  mjs: "js"
-};
 function collectComponentFiles(dir, depth = 0) {
   if (depth > 20) return [];
   const results = [];
@@ -86,27 +79,50 @@ 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 dashboardComponents = /* @__PURE__ */ new Set();
+  const dashboardSrc = findDashboardSrc();
+  if (dashboardSrc) {
+    for (const f of collectComponentFiles(dashboardSrc)) {
+      const cName = getComponentName(f);
+      if (cName) dashboardComponents.add(cName);
+    }
+  }
   if (import_fs.default.existsSync(componentsDir)) {
-    const collectedFiles = collectComponentFiles(componentsDir).sort();
-    for (const fullPath of collectedFiles) {
-      const fileName = import_path.default.basename(fullPath);
-      const name = fileName.replace(/\.(tsx?|jsx?|mts|mjs)$/, "");
+    for (const fullPath of collectComponentFiles(componentsDir).sort()) {
+      const name = import_path.default.basename(fullPath).replace(/\.(tsx?|jsx?|mts|mjs)$/, "");
       if (name && name !== "index") {
-        if (overridesByName.has(name) && process.env.NODE_ENV === "development") {
-          console.warn(
-            `[custom-dashboard] Duplicate override "${name}": ${overridesByName.get(name)} will be replaced by ${fullPath}`
-          );
-        }
         overridesByName.set(name, fullPath);
       }
     }
   }
   const hasOverrides = overridesByName.size > 0;
-  if (hasOverrides && process.env.NODE_ENV === "development") {
-    console.log("[custom-dashboard] overrides:", [...overridesByName.keys()]);
+  let currentServer = null;
+  let watcherCreated = false;
+  const knownOverrideFiles = new Set(overridesByName.values());
+  if (process.env.NODE_ENV === "development") {
+    if (hasOverrides) {
+      console.log("[custom-dashboard] overrides:", [...overridesByName.keys()]);
+    }
+    if (dashboardComponents.size > 0) {
+      console.log(
+        `[custom-dashboard] Scanned ${dashboardComponents.size} dashboard components`
+      );
+    }
   }
   return {
     name: "custom-dashboard",
@@ -115,70 +131,159 @@ 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");
-              let contents;
-              try {
-                contents = import_fs.default.readFileSync(srcEntry, "utf-8");
-              } catch {
-                return void 0;
-              }
+      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.onResolve({ filter: /^__mantajs_override__:/ }, (args) => ({
+            path: args.path,
+            external: true
+          }));
+          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 \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 normalizedPath = overridePath.replace(/\\/g, "/");
               if (process.env.NODE_ENV === "development") {
-                console.log(
-                  `[custom-dashboard] Redirecting entry: ${args.path} \u2192 ${srcEntry}`
-                );
+                console.log(`[custom-dashboard] Override: ${componentName} \u2192 ${overridePath}`);
               }
               return {
-                contents,
+                contents: `export * from "${OVERRIDE_PREFIX}${normalizedPath}"`,
                 loader: "tsx",
-                resolveDir: import_path.default.dirname(srcEntry)
+                resolveDir: import_path.default.dirname(args.path)
               };
-            });
-            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;
+          });
+        }
+      });
+      config.optimizeDeps.esbuildOptions.define = {
+        ...config.optimizeDeps.esbuildOptions.define,
+        "__MANTAJS_OVERRIDES__": JSON.stringify(
+          [...overrides.keys()].sort().join(",")
+        )
+      };
+      config.optimizeDeps.force = true;
+    },
+    configureServer(server) {
+      currentServer = server;
+      if (!import_fs.default.existsSync(componentsDir)) return;
+      if (!watcherCreated) {
+        watcherCreated = true;
+        let debounceTimer = null;
+        import_fs.default.watch(componentsDir, { recursive: true }, (_event, filename) => {
+          if (!filename) return;
+          const ext = import_path.default.extname(filename);
+          if (!COMPONENT_EXT_SET.has(ext)) return;
+          const name = import_path.default.basename(filename).replace(/\.(tsx?|jsx?|mts|mjs)$/, "");
+          if (!name || name === "index") return;
+          if (!dashboardComponents.has(name)) return;
+          const fullPath = import_path.default.resolve(componentsDir, filename);
+          const fileExists = import_fs.default.existsSync(fullPath);
+          const wasKnown = knownOverrideFiles.has(fullPath);
+          if (fileExists && wasKnown) {
+            const mods = currentServer?.moduleGraph.getModulesByFile(fullPath);
+            if (mods && mods.size > 0) {
+              for (const mod of mods) {
+                currentServer.moduleGraph.invalidateModule(mod);
               }
-              return void 0;
-            });
+              currentServer.ws.send({
+                type: "update",
+                updates: [...mods].map((mod) => ({
+                  type: "js-update",
+                  path: mod.url,
+                  acceptedPath: mod.url,
+                  timestamp: Date.now(),
+                  explicitImportRequired: false
+                }))
+              });
+              console.log(`[custom-dashboard] Override "${name}" modified \u2192 HMR`);
+            } else {
+              console.log(`[custom-dashboard] Override "${name}" not in graph \u2192 force-reload`);
+              currentServer?.ws.send({ type: "custom", event: "mantajs:force-reload" });
+            }
+            return;
           }
+          if (debounceTimer) clearTimeout(debounceTimer);
+          debounceTimer = setTimeout(async () => {
+            overridesByName.clear();
+            knownOverrideFiles.clear();
+            for (const fp of collectComponentFiles(componentsDir).sort()) {
+              const n = import_path.default.basename(fp).replace(/\.(tsx?|jsx?|mts|mjs)$/, "");
+              if (n && n !== "index") {
+                overridesByName.set(n, fp);
+                knownOverrideFiles.add(fp);
+              }
+            }
+            const action = fileExists ? "created" : "deleted";
+            console.log(`[custom-dashboard] Override "${name}" ${action} \u2192 restarting...`);
+            console.log(`[custom-dashboard] overrides:`, [...overridesByName.keys()]);
+            try {
+              if (!currentServer) {
+                console.warn(`[custom-dashboard] No server available for restart`);
+                return;
+              }
+              await currentServer.restart();
+              currentServer.ws.send({
+                type: "custom",
+                event: "mantajs:force-reload"
+              });
+              console.log(`[custom-dashboard] Force-reload sent to browser`);
+            } catch (e) {
+              console.error(`[custom-dashboard] Restart failed:`, e);
+            }
+          }, 300);
         });
-        config.optimizeDeps.force = true;
       }
     },
+    handleHotUpdate({ file }) {
+      if (knownOverrideFiles.has(file)) {
+        return [];
+      }
+    },
+    transformIndexHtml(html) {
+      return html.replace(
+        "</head>",
+        `<script type="module">
+if (import.meta.hot) {
+  import.meta.hot.on("mantajs:force-reload", () => {
+    const url = new URL(location.href);
+    url.searchParams.set("_r", Date.now().toString());
+    location.replace(url.href);
+  });
+}
+</script>
+</head>`
+      );
+    },
     resolveId(source) {
       if (source === MENU_VIRTUAL_ID) return MENU_RESOLVED_ID;
+      if (source.startsWith(OVERRIDE_PREFIX)) {
+        return source.slice(OVERRIDE_PREFIX.length);
+      }
       return null;
     },
     load(id) {

package/dist/vite-plugin/index.mjs

@@ -3,16 +3,9 @@ import path from "path";
 import fs from "fs";
 var MENU_VIRTUAL_ID = "virtual:dashboard/menu-config";
 var MENU_RESOLVED_ID = "\0" + MENU_VIRTUAL_ID;
+var OVERRIDE_PREFIX = "__mantajs_override__:";
 var COMPONENT_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js", ".mts", ".mjs"];
 var COMPONENT_EXT_SET = new Set(COMPONENT_EXTENSIONS);
-var VALID_LOADERS = {
-  tsx: "tsx",
-  ts: "ts",
-  jsx: "jsx",
-  js: "js",
-  mts: "ts",
-  mjs: "js"
-};
 function collectComponentFiles(dir, depth = 0) {
   if (depth > 20) return [];
   const results = [];
@@ -51,27 +44,50 @@ 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 dashboardComponents = /* @__PURE__ */ new Set();
+  const dashboardSrc = findDashboardSrc();
+  if (dashboardSrc) {
+    for (const f of collectComponentFiles(dashboardSrc)) {
+      const cName = getComponentName(f);
+      if (cName) dashboardComponents.add(cName);
+    }
+  }
   if (fs.existsSync(componentsDir)) {
-    const collectedFiles = collectComponentFiles(componentsDir).sort();
-    for (const fullPath of collectedFiles) {
-      const fileName = path.basename(fullPath);
-      const name = fileName.replace(/\.(tsx?|jsx?|mts|mjs)$/, "");
+    for (const fullPath of collectComponentFiles(componentsDir).sort()) {
+      const name = path.basename(fullPath).replace(/\.(tsx?|jsx?|mts|mjs)$/, "");
       if (name && name !== "index") {
-        if (overridesByName.has(name) && process.env.NODE_ENV === "development") {
-          console.warn(
-            `[custom-dashboard] Duplicate override "${name}": ${overridesByName.get(name)} will be replaced by ${fullPath}`
-          );
-        }
         overridesByName.set(name, fullPath);
       }
     }
   }
   const hasOverrides = overridesByName.size > 0;
-  if (hasOverrides && process.env.NODE_ENV === "development") {
-    console.log("[custom-dashboard] overrides:", [...overridesByName.keys()]);
+  let currentServer = null;
+  let watcherCreated = false;
+  const knownOverrideFiles = new Set(overridesByName.values());
+  if (process.env.NODE_ENV === "development") {
+    if (hasOverrides) {
+      console.log("[custom-dashboard] overrides:", [...overridesByName.keys()]);
+    }
+    if (dashboardComponents.size > 0) {
+      console.log(
+        `[custom-dashboard] Scanned ${dashboardComponents.size} dashboard components`
+      );
+    }
   }
   return {
     name: "custom-dashboard",
@@ -80,70 +96,159 @@ 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");
-              let contents;
-              try {
-                contents = fs.readFileSync(srcEntry, "utf-8");
-              } catch {
-                return void 0;
-              }
+      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.onResolve({ filter: /^__mantajs_override__:/ }, (args) => ({
+            path: args.path,
+            external: true
+          }));
+          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 \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 normalizedPath = overridePath.replace(/\\/g, "/");
               if (process.env.NODE_ENV === "development") {
-                console.log(
-                  `[custom-dashboard] Redirecting entry: ${args.path} \u2192 ${srcEntry}`
-                );
+                console.log(`[custom-dashboard] Override: ${componentName} \u2192 ${overridePath}`);
               }
               return {
-                contents,
+                contents: `export * from "${OVERRIDE_PREFIX}${normalizedPath}"`,
                 loader: "tsx",
-                resolveDir: path.dirname(srcEntry)
+                resolveDir: path.dirname(args.path)
               };
-            });
-            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;
+          });
+        }
+      });
+      config.optimizeDeps.esbuildOptions.define = {
+        ...config.optimizeDeps.esbuildOptions.define,
+        "__MANTAJS_OVERRIDES__": JSON.stringify(
+          [...overrides.keys()].sort().join(",")
+        )
+      };
+      config.optimizeDeps.force = true;
+    },
+    configureServer(server) {
+      currentServer = server;
+      if (!fs.existsSync(componentsDir)) return;
+      if (!watcherCreated) {
+        watcherCreated = true;
+        let debounceTimer = null;
+        fs.watch(componentsDir, { recursive: true }, (_event, filename) => {
+          if (!filename) return;
+          const ext = path.extname(filename);
+          if (!COMPONENT_EXT_SET.has(ext)) return;
+          const name = path.basename(filename).replace(/\.(tsx?|jsx?|mts|mjs)$/, "");
+          if (!name || name === "index") return;
+          if (!dashboardComponents.has(name)) return;
+          const fullPath = path.resolve(componentsDir, filename);
+          const fileExists = fs.existsSync(fullPath);
+          const wasKnown = knownOverrideFiles.has(fullPath);
+          if (fileExists && wasKnown) {
+            const mods = currentServer?.moduleGraph.getModulesByFile(fullPath);
+            if (mods && mods.size > 0) {
+              for (const mod of mods) {
+                currentServer.moduleGraph.invalidateModule(mod);
               }
-              return void 0;
-            });
+              currentServer.ws.send({
+                type: "update",
+                updates: [...mods].map((mod) => ({
+                  type: "js-update",
+                  path: mod.url,
+                  acceptedPath: mod.url,
+                  timestamp: Date.now(),
+                  explicitImportRequired: false
+                }))
+              });
+              console.log(`[custom-dashboard] Override "${name}" modified \u2192 HMR`);
+            } else {
+              console.log(`[custom-dashboard] Override "${name}" not in graph \u2192 force-reload`);
+              currentServer?.ws.send({ type: "custom", event: "mantajs:force-reload" });
+            }
+            return;
           }
+          if (debounceTimer) clearTimeout(debounceTimer);
+          debounceTimer = setTimeout(async () => {
+            overridesByName.clear();
+            knownOverrideFiles.clear();
+            for (const fp of collectComponentFiles(componentsDir).sort()) {
+              const n = path.basename(fp).replace(/\.(tsx?|jsx?|mts|mjs)$/, "");
+              if (n && n !== "index") {
+                overridesByName.set(n, fp);
+                knownOverrideFiles.add(fp);
+              }
+            }
+            const action = fileExists ? "created" : "deleted";
+            console.log(`[custom-dashboard] Override "${name}" ${action} \u2192 restarting...`);
+            console.log(`[custom-dashboard] overrides:`, [...overridesByName.keys()]);
+            try {
+              if (!currentServer) {
+                console.warn(`[custom-dashboard] No server available for restart`);
+                return;
+              }
+              await currentServer.restart();
+              currentServer.ws.send({
+                type: "custom",
+                event: "mantajs:force-reload"
+              });
+              console.log(`[custom-dashboard] Force-reload sent to browser`);
+            } catch (e) {
+              console.error(`[custom-dashboard] Restart failed:`, e);
+            }
+          }, 300);
         });
-        config.optimizeDeps.force = true;
       }
     },
+    handleHotUpdate({ file }) {
+      if (knownOverrideFiles.has(file)) {
+        return [];
+      }
+    },
+    transformIndexHtml(html) {
+      return html.replace(
+        "</head>",
+        `<script type="module">
+if (import.meta.hot) {
+  import.meta.hot.on("mantajs:force-reload", () => {
+    const url = new URL(location.href);
+    url.searchParams.set("_r", Date.now().toString());
+    location.replace(url.href);
+  });
+}
+</script>
+</head>`
+      );
+    },
     resolveId(source) {
       if (source === MENU_VIRTUAL_ID) return MENU_RESOLVED_ID;
+      if (source.startsWith(OVERRIDE_PREFIX)) {
+        return source.slice(OVERRIDE_PREFIX.length);
+      }
       return null;
     },
     load(id) {

package/package.json

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

package/src/vite-plugin/index.ts

@@ -1,22 +1,17 @@
-import { Plugin } from "vite"
+import { Plugin, ViteDevServer } from "vite"
 import path from "path"
 import fs from "fs"
 
 const MENU_VIRTUAL_ID = "virtual:dashboard/menu-config"
 const MENU_RESOLVED_ID = "\0" + MENU_VIRTUAL_ID
 
+// Unique prefix for override imports — esbuild marks these as external,
+// then Vite's resolveId resolves them to the actual file paths.
+const OVERRIDE_PREFIX = "__mantajs_override__:"
+
 const COMPONENT_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js", ".mts", ".mjs"]
 const COMPONENT_EXT_SET = new Set(COMPONENT_EXTENSIONS)
 
-const VALID_LOADERS: Record<string, string> = {
-  tsx: "tsx",
-  ts: "ts",
-  jsx: "jsx",
-  js: "js",
-  mts: "ts",
-  mjs: "js",
-}
-
 /**
  * Recursively collect all component files from a directory tree.
  * Includes a depth guard to prevent symlink loops and skips hidden
@@ -68,29 +63,66 @@ 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.
  *
  * Handles:
  * 1. Menu config virtual module (virtual:dashboard/menu-config)
- * 2. Component overrides — any file in src/admin/components/ overrides the
- *    dashboard component with the same name.
+ * 2. Component overrides — any file in src/admin/components/ whose name
+ *    matches a dashboard component replaces it at build time.
+ *
+ * HMR Architecture:
+ * - Override files are NOT inlined into the esbuild pre-bundled chunk.
+ *   Instead, the chunk contains `export * from "/@fs/path/to/override.tsx"`,
+ *   keeping the override as a **separate Vite module**.
+ * - Because the override is a separate module exporting React components,
+ *   @vitejs/plugin-react adds React Fast Refresh boundaries
+ *   (import.meta.hot.accept). This makes the module self-accepting for HMR.
+ * - On MODIFICATION: Vite detects the file change, transforms it, and sends
+ *   an HMR update. React Fast Refresh swaps the component — no page reload.
+ * - On CREATION or DELETION: The esbuild pre-bundle must be rebuilt (the
+ *   chunk structure changes). We restart Vite + send a full-reload to the
+ *   browser so it picks up the new chunks automatically.
+ * - The fs.watch is independent from Vite's internal watcher, so it
+ *   survives server.restart() calls without losing events.
  */
 export function customDashboardPlugin(): Plugin {
   const componentsDir = path.resolve(process.cwd(), "src/admin/components")
   const overridesByName = new Map<string, string>()
 
+  // Scan dashboard source once at startup — used to decide if a changed
+  // file is a potential override (~966 names, ~30 KB).
+  const dashboardComponents = new Set<string>()
+  const dashboardSrc = findDashboardSrc()
+  if (dashboardSrc) {
+    for (const f of collectComponentFiles(dashboardSrc)) {
+      const cName = getComponentName(f)
+      if (cName) dashboardComponents.add(cName)
+    }
+  }
+
+  // Collect initial overrides from disk
   if (fs.existsSync(componentsDir)) {
-    const collectedFiles = collectComponentFiles(componentsDir).sort()
-    for (const fullPath of collectedFiles) {
-      const fileName = path.basename(fullPath)
-      const name = fileName.replace(/\.(tsx?|jsx?|mts|mjs)$/, "")
+    for (const fullPath of collectComponentFiles(componentsDir).sort()) {
+      const name = path.basename(fullPath).replace(/\.(tsx?|jsx?|mts|mjs)$/, "")
       if (name && name !== "index") {
-        if (overridesByName.has(name) && process.env.NODE_ENV === "development") {
-          console.warn(
-            `[custom-dashboard] Duplicate override "${name}": ${overridesByName.get(name)} will be replaced by ${fullPath}`
-          )
-        }
         overridesByName.set(name, fullPath)
       }
     }
@@ -98,8 +130,22 @@ export function customDashboardPlugin(): Plugin {
 
   const hasOverrides = overridesByName.size > 0
 
-  if (hasOverrides && process.env.NODE_ENV === "development") {
-    console.log("[custom-dashboard] overrides:", [...overridesByName.keys()])
+  // Mutable ref to the latest Vite server — updated on each configureServer
+  let currentServer: ViteDevServer | null = null
+  let watcherCreated = false
+
+  // Track known override file paths to distinguish modify vs create/delete
+  const knownOverrideFiles = new Set<string>(overridesByName.values())
+
+  if (process.env.NODE_ENV === "development") {
+    if (hasOverrides) {
+      console.log("[custom-dashboard] overrides:", [...overridesByName.keys()])
+    }
+    if (dashboardComponents.size > 0) {
+      console.log(
+        `[custom-dashboard] Scanned ${dashboardComponents.size} dashboard components`
+      )
+    }
   }
 
   return {
@@ -107,98 +153,218 @@ export function customDashboardPlugin(): Plugin {
     enforce: "pre",
 
     config(config) {
-      // Always exclude the menu virtual module
       config.optimizeDeps = config.optimizeDeps || {}
       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")
-
-              let contents: string
-              try {
-                contents = fs.readFileSync(srcEntry, "utf-8")
-              } catch {
-                return undefined
-              }
+      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) {
+          // Mark override imports as external — this keeps override files as
+          // separate ES modules that Vite processes individually, enabling
+          // React Fast Refresh HMR instead of requiring a full page reload.
+          build.onResolve({ filter: /^__mantajs_override__:/ }, (args) => ({
+            path: args.path,
+            external: true,
+          }))
+
+          // Redirect dist entry → source so esbuild processes individual files
+          build.onLoad({ filter: /app\.(mjs|js)$/ }, (args) => {
+            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 → ${srcEntry}`)
+            }
+            return { contents, loader: "tsx", resolveDir: path.dirname(srcEntry) }
+          })
+
+          // For overridden components, emit a re-export from /@fs/ instead of
+          // inlining the file contents. The override becomes a separate Vite
+          // module with full HMR support via React Fast Refresh.
+          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
+
+            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 normalizedPath = overridePath.replace(/\\/g, "/")
 
               if (process.env.NODE_ENV === "development") {
-                console.log(
-                  `[custom-dashboard] Redirecting entry: ${args.path} → ${srcEntry}`
-                )
+                console.log(`[custom-dashboard] Override: ${componentName} → ${overridePath}`)
               }
               return {
-                contents,
+                contents: `export * from "${OVERRIDE_PREFIX}${normalizedPath}"`,
                 loader: "tsx",
-                resolveDir: path.dirname(srcEntry),
+                resolveDir: path.dirname(args.path),
+              }
+            }
+            return undefined
+          })
+        },
+      })
+
+      // Include override state in esbuild define — this changes Vite's dep
+      // optimization hash (?v=xxx), forcing the browser to fetch fresh chunks
+      // whenever overrides are added or removed (prevents stale cache 404s).
+      config.optimizeDeps.esbuildOptions.define = {
+        ...config.optimizeDeps.esbuildOptions.define,
+        '__MANTAJS_OVERRIDES__': JSON.stringify(
+          [...overrides.keys()].sort().join(',')
+        ),
+      }
+      config.optimizeDeps.force = true
+    },
+
+    configureServer(server: ViteDevServer) {
+      // Always update server ref (called again after each server.restart())
+      currentServer = server
+
+      if (!fs.existsSync(componentsDir)) return
+
+      // Create ONE independent watcher that survives server.restart().
+      // Uses Node's fs.watch (FSEvents on macOS) — lightweight, no polling.
+      if (!watcherCreated) {
+        watcherCreated = true
+        let debounceTimer: ReturnType<typeof setTimeout> | null = null
+
+        fs.watch(componentsDir, { recursive: true }, (_event, filename) => {
+          if (!filename) return
+          const ext = path.extname(filename)
+          if (!COMPONENT_EXT_SET.has(ext)) return
+
+          const name = path.basename(filename).replace(/\.(tsx?|jsx?|mts|mjs)$/, "")
+          if (!name || name === "index") return
+
+          // Only act if this file name matches a dashboard component
+          if (!dashboardComponents.has(name)) return
+
+          const fullPath = path.resolve(componentsDir, filename)
+          const fileExists = fs.existsSync(fullPath)
+          const wasKnown = knownOverrideFiles.has(fullPath)
+
+          if (fileExists && wasKnown) {
+            // MODIFICATION — send HMR update ourselves. After server.restart(),
+            // Vite's internal chokidar may not fire for override files, so we
+            // handle it entirely from our independent fs.watch.
+            const mods = currentServer?.moduleGraph.getModulesByFile(fullPath)
+            if (mods && mods.size > 0) {
+              for (const mod of mods) {
+                currentServer!.moduleGraph.invalidateModule(mod)
               }
-            })
-
-            // 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),
-                }
+              currentServer!.ws.send({
+                type: "update",
+                updates: [...mods].map((mod) => ({
+                  type: "js-update" as const,
+                  path: mod.url,
+                  acceptedPath: mod.url,
+                  timestamp: Date.now(),
+                  explicitImportRequired: false,
+                })),
+              })
+              console.log(`[custom-dashboard] Override "${name}" modified → HMR`)
+            } else {
+              console.log(`[custom-dashboard] Override "${name}" not in graph → force-reload`)
+              currentServer?.ws.send({ type: "custom", event: "mantajs:force-reload" })
+            }
+            return
+          }
+
+          // CREATION or DELETION — the esbuild pre-bundle must be rebuilt
+          // because the chunk structure changes (new external ref or removed).
+          if (debounceTimer) clearTimeout(debounceTimer)
+          debounceTimer = setTimeout(async () => {
+            // Re-scan overrides from disk
+            overridesByName.clear()
+            knownOverrideFiles.clear()
+            for (const fp of collectComponentFiles(componentsDir).sort()) {
+              const n = path.basename(fp).replace(/\.(tsx?|jsx?|mts|mjs)$/, "")
+              if (n && n !== "index") {
+                overridesByName.set(n, fp)
+                knownOverrideFiles.add(fp)
               }
-              return undefined
-            })
-          },
+            }
+
+            const action = fileExists ? "created" : "deleted"
+            console.log(`[custom-dashboard] Override "${name}" ${action} → restarting...`)
+            console.log(`[custom-dashboard] overrides:`, [...overridesByName.keys()])
+
+            // Vite preserves the WebSocket connection across restart() — the
+            // browser never disconnects. Await restart, then tell the client
+            // to do a cache-busting reload (location.reload() reuses cached
+            // modules; our custom event navigates to a timestamped URL instead).
+            try {
+              if (!currentServer) {
+                console.warn(`[custom-dashboard] No server available for restart`)
+                return
+              }
+              await currentServer.restart()
+              currentServer.ws.send({
+                type: "custom",
+                event: "mantajs:force-reload",
+              })
+              console.log(`[custom-dashboard] Force-reload sent to browser`)
+            } catch (e) {
+              console.error(`[custom-dashboard] Restart failed:`, e)
+            }
+          }, 300)
         })
+      }
+    },
 
-        // Force re-optimisation so overrides are always applied
-        config.optimizeDeps.force = true
+    handleHotUpdate({ file }) {
+      // Suppress Vite's default HMR for override files — our fs.watch
+      // handles modifications (HMR) and deletions (restart) instead.
+      if (knownOverrideFiles.has(file)) {
+        return []
       }
     },
 
+    transformIndexHtml(html) {
+      // Inject a client-side script that listens for our force-reload event.
+      // Unlike location.reload(), this navigates to a cache-busting URL so
+      // the browser re-fetches all modules (including pre-bundled chunks).
+      return html.replace(
+        "</head>",
+        `<script type="module">
+if (import.meta.hot) {
+  import.meta.hot.on("mantajs:force-reload", () => {
+    const url = new URL(location.href);
+    url.searchParams.set("_r", Date.now().toString());
+    location.replace(url.href);
+  });
+}
+</script>
+</head>`
+      )
+    },
+
     resolveId(source) {
       if (source === MENU_VIRTUAL_ID) return MENU_RESOLVED_ID
+      // Resolve override imports to the actual file path — Vite then serves
+      // the file through its transform pipeline (including React Fast Refresh).
+      if (source.startsWith(OVERRIDE_PREFIX)) {
+        return source.slice(OVERRIDE_PREFIX.length)
+      }
       return null
     },