The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
import type * as Vite from "vite";
import path from "path";
import fs from "fs";
import { createRequire } from "module";
import { getFileExports } from "./utils";
import {
LAYOUT_PREFERENCES_FILE,
NAVIGATION_FILE,
RESOLVED_ROUTES_MODULE,
RESOLVED_MENU_ITEMS_MODULE,
RESOLVED_WIDGETS_MODULE,
RESOLVED_NAVIGATION_MODULE,
RESOLVED_CUSTOM_FIELDS_MODULE,
RESOLVED_LAYOUTS_MODULE,
RESOLVED_PREFERENCES_MODULE,
RESOLVED_I18N_MODULE,
VIRTUAL_MODULES,
} from "./constants";
import {
isVirtualModule,
resolveVirtualModule,
loadVirtualModule,
} from "./virtual-modules";
import type { MercurConfig, BuiltMercurConfig } from "./types";
function isRouteFile(file: string): boolean {
const basename = path.basename(file, path.extname(file));
return basename === "page";
}
function isWidgetFile(file: string): boolean {
return normalizeSep(file).includes("/src/widgets/");
}
function isNavigationFile(file: string): boolean {
const basename = path.basename(file, path.extname(file));
return basename === NAVIGATION_FILE;
}
function isPreferencesFile(file: string): boolean {
const basename = path.basename(file, path.extname(file));
return basename === LAYOUT_PREFERENCES_FILE;
}
function isCustomFieldFile(file: string): boolean {
return normalizeSep(file).includes("/src/custom-fields/");
}
function isLayoutFile(file: string): boolean {
return normalizeSep(file).includes("/layouts/");
}
function isI18nFile(file: string): boolean {
return normalizeSep(file).includes("/i18n/");
}
// Every virtual module reads every layer, so a change in one kind of file
// invalidates them all; the cost is one re-crawl per edit.
const LAYERED_MODULES = [
RESOLVED_ROUTES_MODULE,
RESOLVED_MENU_ITEMS_MODULE,
RESOLVED_WIDGETS_MODULE,
RESOLVED_NAVIGATION_MODULE,
RESOLVED_CUSTOM_FIELDS_MODULE,
RESOLVED_LAYOUTS_MODULE,
RESOLVED_PREFERENCES_MODULE,
RESOLVED_I18N_MODULE,
];
function isExtensionFile(file: string): boolean {
return (
isRouteFile(file) ||
isWidgetFile(file) ||
isNavigationFile(file) ||
isPreferencesFile(file) ||
isCustomFieldFile(file) ||
isLayoutFile(file) ||
isI18nFile(file)
);
}
function normalizeSep(file: string): string {
return file.replace(/\\/g, "/");
}
const UI_MODULE_KEYS = ["admin_ui", "vendor_ui"];
// `@medusajs/dashboard` declares `virtual:medusa/*` imports that are resolved
// upstream by `@medusajs/admin-vite-plugin`. Mercur replaces those modules at
// bundle time, so the runtime never actually loads them — but esbuild's
// dependency scanner still walks `@medusajs/dashboard/dist/app.mjs` and fails
// on the unresolved specifiers. Stubbing them keeps the scan happy.
const MEDUSA_VIRTUAL_MODULES = [
"virtual:medusa/displays",
"virtual:medusa/forms",
"virtual:medusa/i18n",
"virtual:medusa/layouts",
"virtual:medusa/cell-renderers",
"virtual:medusa/menu-items",
"virtual:medusa/routes",
"virtual:medusa/widgets",
"virtual:medusa/links",
"virtual:medusa/search-entities",
];
function isMedusaVirtualModule(id: string): boolean {
return MEDUSA_VIRTUAL_MODULES.includes(id);
}
// Only force-prebundle deps that actually resolve from the app. Consuming apps
// (e.g. templates) may not declare optional deps like `i18next` or
// `@medusajs/dashboard` directly, and Vite warns for every unresolved entry in
// `optimizeDeps.include`.
function filterResolvableDeps(specifiers: string[], fromDir: string): string[] {
const require = createRequire(path.join(fromDir, "noop.js"));
return specifiers.filter((specifier) => {
try {
require.resolve(specifier);
return true;
} catch {
return false;
}
});
}
function resolveMedusaVirtualModule(id: string): string {
return "\0" + id;
}
function isResolvedMedusaVirtualModule(id: string): boolean {
return id.startsWith("\0virtual:medusa/");
}
function findNodeModulesRoot(configDir: string): string {
// Walk up from configDir to find the nearest node_modules
let dir = configDir;
while (dir !== path.dirname(dir)) {
const candidate = path.join(dir, "node_modules");
if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
return candidate;
}
dir = path.dirname(dir);
}
return path.join(configDir, "node_modules");
}
function resolvePluginRoot(
resolve: string,
configDir: string,
nodeModulesRoot: string,
): string | null {
if (resolve.startsWith(".")) {
try {
const resolved = path.resolve(configDir, resolve);
return fs.existsSync(resolved) ? fs.realpathSync(resolved) : null;
} catch {
return null;
}
}
// Ask Node how it would resolve the specifier rather than guessing a single
// directory. `findNodeModulesRoot` returns the *nearest* node_modules, which
// in a monorepo is the app's own — holding only that app's dependencies —
// while workspace symlinks live at the repo root. Node walks every level.
const require = createRequire(path.join(configDir, "noop.js"));
try {
return fs.realpathSync(
path.dirname(require.resolve(`${resolve}/package.json`)),
);
} catch {
// `exports` may not expose package.json; fall back to the entry point
// and walk up to the directory that owns it.
}
try {
let dir = path.dirname(require.resolve(resolve));
while (dir !== path.dirname(dir)) {
if (fs.existsSync(path.join(dir, "package.json"))) {
return fs.realpathSync(dir);
}
dir = path.dirname(dir);
}
} catch {
// Not resolvable from the app — fall through to the directory probe.
}
try {
const packagePath = path.join(nodeModulesRoot, resolve);
return fs.existsSync(packagePath) ? fs.realpathSync(packagePath) : null;
} catch {
return null;
}
}
function resolvePluginExtensions(plugins: any[], configDir: string, appType: "admin" | "vendor"): string[] {
const nodeModulesRoot = findNodeModulesRoot(configDir);
const extensions: string[] = [];
for (const plugin of plugins) {
const resolve = typeof plugin === "string" ? plugin : plugin?.resolve;
if (!resolve || typeof resolve !== "string") continue;
const pluginRoot = resolvePluginRoot(resolve, configDir, nodeModulesRoot);
if (!pluginRoot) {
// Silently skipping leaves the dashboard missing whatever the plugin
// contributes, with a build that still looks clean.
console.warn(
`[@mercurjs/dashboard-sdk] Could not resolve plugin "${resolve}" from ${configDir}. ` +
`Its ${appType} extensions will be missing from the build.`,
);
continue;
}
const extFile = path.join(
pluginRoot,
".medusa/server/src",
appType,
"index.mjs",
);
if (fs.existsSync(extFile)) {
extensions.push(extFile);
}
}
return extensions;
}
function trimTrailingSlashes(value: string): string {
let end = value.length;
while (end > 0 && value.charCodeAt(end - 1) === 47) {
end -= 1;
}
return end === value.length ? value : value.slice(0, end);
}
async function loadMedusaConfig(
medusaConfigPath: string,
root: string,
options: {
isDevelopment: boolean;
vendorUrl?: string;
},
): Promise<{
base?: string;
pluginExtensions: string[];
projectDir?: string;
vendorAppUrl?: string;
}> {
const configDir = path.dirname(medusaConfigPath);
try {
// Medusa configs assume they execute from their own directory — `medusa` itself
// runs them that way (loadEnv(process.cwd()), cwd-relative module resolution).
// We load the config from a panel's directory, so emulate Medusa's cwd for the
// duration of the import.
const previousCwd = process.cwd();
let mod: Awaited<ReturnType<typeof getFileExports>>;
process.chdir(configDir);
try {
mod = await getFileExports(medusaConfigPath);
} finally {
process.chdir(previousCwd);
}
const medusaConfig = mod.default ?? mod;
const modules = medusaConfig?.modules ?? {};
let base: string | undefined;
let appType: "admin" | "vendor" = "admin";
let vendorAppUrl: string | undefined;
const vendorModule = modules.vendor_ui;
const vendorPath = vendorModule?.options?.path ?? "/seller";
if (options.vendorUrl) {
vendorAppUrl = trimTrailingSlashes(options.vendorUrl);
} else if (options.isDevelopment) {
const vendorHost =
vendorModule?.options?.viteDevServerHost ?? "localhost";
const vendorPort =
vendorModule?.options?.viteDevServerPort ?? 7001;
vendorAppUrl = `http://${vendorHost}:${vendorPort}${vendorPath}`;
} else {
vendorAppUrl = vendorPath;
}
for (const key of UI_MODULE_KEYS) {
const value = modules[key];
if (!value || typeof value !== "object" || !value.options?.appDir)
continue;
const appDir = path.resolve(configDir, value.options.appDir);
if (appDir === root) {
base = value.options.path;
appType = key === "vendor_ui" ? "vendor" : "admin";
break;
}
}
const plugins =
medusaConfig?.plugins?.filter(
(plugin: { resolve: string }) =>
plugin.resolve !== "@medusajs/draft-order",
) ?? [];
const pluginExtensions = resolvePluginExtensions(plugins, configDir, appType);
// The Medusa project's own panel extensions live beside its backend code,
// as `src/admin` does for Medusa's admin.
const projectCandidate = path.join(configDir, "src", appType);
const projectDir =
fs.existsSync(projectCandidate) && fs.realpathSync(projectCandidate) !== root
? projectCandidate
: undefined;
return { base, pluginExtensions, projectDir, vendorAppUrl };
} catch (error) {
// Don't fail the build — but never fail silently either: without the Medusa config
// the panel is built with base "/" and no plugin extensions, and a panel served
// under a sub-path (e.g. /dashboard) would then request assets that 404.
console.warn(
`[@mercurjs/dashboard-sdk] Could not load the Medusa config from "${medusaConfigPath}": ` +
`${error instanceof Error ? error.message : String(error)}. ` +
`Building with base "/" and no plugin extensions — if this panel is served ` +
`under a sub-path (e.g. /dashboard), its assets will not resolve.`,
);
return { pluginExtensions: [] };
}
}
export function mercurDashboardPlugin(pluginConfig: MercurConfig): Vite.Plugin {
let root: string;
let config: BuiltMercurConfig;
return {
name: "@mercurjs/dashboard-sdk",
async config(viteConfig) {
root = viteConfig.root || process.cwd();
const isDevelopment =
(viteConfig.mode || process.env.NODE_ENV || "development") !==
"production";
const medusaConfigPath = path.resolve(
root,
pluginConfig.medusaConfigPath,
);
const { base, pluginExtensions, projectDir, vendorAppUrl } = await loadMedusaConfig(
medusaConfigPath,
root,
{
isDevelopment,
vendorUrl: pluginConfig.vendorUrl,
},
);
const srcDir = path.join(root, "src");
const backendUrl = pluginConfig.backendUrl ?? "http://localhost:9000";
const imageLimit = pluginConfig.imageLimit ?? 2 * 1024 * 1024;
config = {
...pluginConfig,
backendUrl,
base,
root,
srcDir,
projectDir,
pluginExtensions,
imageLimit,
};
return {
base: config.base,
define: {
__BACKEND_URL__: JSON.stringify(config.backendUrl),
__BASE__: JSON.stringify(config.base || "/"),
__VENDOR_URL__: JSON.stringify(vendorAppUrl || ""),
},
resolve: {
dedupe: ["i18next", "react-i18next", "react", "react-dom"],
},
optimizeDeps: {
exclude: [...VIRTUAL_MODULES, ...MEDUSA_VIRTUAL_MODULES],
include: filterResolvableDeps(
[
"react",
"react/jsx-runtime",
"react-dom/client",
"react-router-dom",
"react-i18next",
"i18next",
"@medusajs/ui",
"@medusajs/dashboard",
"@mercurjs/client",
"@tanstack/react-query",
],
root,
),
},
};
},
configResolved(resolvedConfig) {
root = resolvedConfig.root;
},
resolveId(id) {
if (isVirtualModule(id)) {
return resolveVirtualModule(id);
}
if (isMedusaVirtualModule(id)) {
return resolveMedusaVirtualModule(id);
}
return null;
},
load(id) {
if (isResolvedMedusaVirtualModule(id)) {
return "export default {}";
}
return loadVirtualModule({ id, mercurConfig: config });
},
configureServer(server) {
const invalidate = (moduleId: string, reload: boolean) => {
const mod = server.moduleGraph.getModuleById(moduleId);
if (mod) {
server.moduleGraph.invalidateModule(mod);
if (reload) server.ws.send({ type: "full-reload" });
}
};
const handleChange = (file: string) => {
if (!isExtensionFile(file)) return;
for (const moduleId of LAYERED_MODULES) invalidate(moduleId, false);
server.ws.send({ type: "full-reload" });
};
server.watcher.on("add", handleChange);
server.watcher.on("unlink", handleChange);
},
handleHotUpdate({ file, server }) {
const invalidate = (moduleId: string) => {
const mod = server.moduleGraph.getModuleById(moduleId);
if (mod) server.moduleGraph.invalidateModule(mod);
};
if (!isExtensionFile(file)) return;
for (const moduleId of LAYERED_MODULES) invalidate(moduleId);
},
};
}