@vercel/microfrontends 2.2.0 → 2.2.2

package/dist/bin/cli.cjs

@@ -24,13 +24,13 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/bin/index.ts
-var import_commander = require("commander");
 var import_env = require("@next/env");
+var import_commander = require("commander");
 
 // package.json
 var package_default = {
   name: "@vercel/microfrontends",
-  version: "2.2.0",
+  version: "2.2.2",
   private: false,
   description: "Defines configuration and utilities for microfrontends development",
   keywords: [
@@ -161,15 +161,14 @@ var package_default = {
     postbuild: "pnpm generate:exports",
     "generate:exports": "tsx scripts/generate-exports/index.ts",
     "generate:schema": "tsx scripts/generate-json-schema.ts",
-    lint: "eslint .",
-    "lint-fix": "eslint . --fix",
+    lint: "biome check",
     prepublishOnly: "pnpm build && pnpm generate:exports && pnpm generate:schema",
     proxy: "tsx src/proxy/index.ts",
     test: "cross-env TZ=UTC jest",
     typecheck: "tsc --noEmit"
   },
   dependencies: {
-    "@next/env": "15.5.4",
+    "@next/env": "16.0.10",
     "@types/md5": "^2.3.5",
     ajv: "^8.17.1",
     commander: "^12.1.0",
@@ -195,10 +194,9 @@ var package_default = {
     "@types/react": "18.3.1",
     "@types/react-dom": "18.3.0",
     "@types/semver": "^7.7.0",
-    "eslint-config-custom": "workspace:*",
     jest: "^29.7.0",
     "jest-environment-jsdom": "29.2.2",
-    next: "15.5.4",
+    next: "16.0.10",
     react: "19.0.0",
     "react-dom": "19.0.0",
     "ts-config": "workspace:*",
@@ -249,11 +247,34 @@ var http = __toESM(require("http"), 1);
 var https = __toESM(require("https"), 1);
 var import_node_url = require("url");
 var import_cookie = require("cookie");
-var import_path_to_regexp3 = require("path-to-regexp");
 var import_http_proxy = __toESM(require("http-proxy"), 1);
+var import_path_to_regexp3 = require("path-to-regexp");
 
-// src/config/microfrontends-config/isomorphic/index.ts
-var import_jsonc_parser = require("jsonc-parser");
+// src/config/microfrontends/server/index.ts
+var import_node_fs7 = __toESM(require("fs"), 1);
+var import_node_path8 = require("path");
+
+// src/bin/logger.ts
+function debug(...args) {
+  if (process.env.MFE_DEBUG) {
+    console.log(...args);
+  }
+}
+function info(...args) {
+  console.log(...args);
+}
+function warn(...args) {
+  console.warn(...args);
+}
+function error(...args) {
+  console.error(...args);
+}
+var logger = {
+  debug,
+  info,
+  warn,
+  error
+};
 
 // src/config/errors.ts
 var MicrofrontendError = class extends Error {
@@ -347,27 +368,18 @@ var MicrofrontendError = class extends Error {
   }
 };
 
-// src/config/microfrontends-config/utils/get-config-from-env.ts
-function getConfigStringFromEnv() {
-  const config = process.env.MFE_CONFIG;
-  if (!config) {
-    throw new MicrofrontendError(`Missing "MFE_CONFIG" in environment.`, {
-      type: "config",
-      subtype: "not_found_in_env"
-    });
-  }
-  return config;
-}
-
-// src/config/schema/utils/is-default-app.ts
-function isDefaultApp(a) {
-  return !("routing" in a);
-}
+// src/config/microfrontends-config/isomorphic/index.ts
+var import_jsonc_parser = require("jsonc-parser");
 
 // src/config/overrides/constants.ts
 var OVERRIDES_COOKIE_PREFIX = "vercel-micro-frontends-override";
 var OVERRIDES_ENV_COOKIE_PREFIX = `${OVERRIDES_COOKIE_PREFIX}:env:`;
 
+// src/config/overrides/get-app-env-override-cookie-name.ts
+function getAppEnvOverrideCookieName(application) {
+  return `${OVERRIDES_ENV_COOKIE_PREFIX}${application}`;
+}
+
 // src/config/overrides/is-override-cookie.ts
 function isOverrideCookie(cookie) {
   return Boolean(cookie.name?.startsWith(OVERRIDES_COOKIE_PREFIX));
@@ -397,9 +409,9 @@ function parseOverrides(cookies) {
   return overridesConfig;
 }
 
-// src/config/overrides/get-app-env-override-cookie-name.ts
-function getAppEnvOverrideCookieName(application) {
-  return `${OVERRIDES_ENV_COOKIE_PREFIX}${application}`;
+// src/config/schema/utils/is-default-app.ts
+function isDefaultApp(a) {
+  return !("routing" in a);
 }
 
 // src/config/microfrontends-config/client/index.ts
@@ -500,6 +512,183 @@ var MicrofrontendConfigClient = class {
   }
 };
 
+// src/config/microfrontends-config/utils/get-config-from-env.ts
+function getConfigStringFromEnv() {
+  const config = process.env.MFE_CONFIG;
+  if (!config) {
+    throw new MicrofrontendError(`Missing "MFE_CONFIG" in environment.`, {
+      type: "config",
+      subtype: "not_found_in_env"
+    });
+  }
+  return config;
+}
+
+// src/config/microfrontends-config/isomorphic/constants.ts
+var DEFAULT_LOCAL_PROXY_PORT = 3024;
+var MFE_APP_PORT_ENV = "MFE_APP_PORT";
+var MFE_LOCAL_PROXY_PORT_ENV = "MFE_LOCAL_PROXY_PORT";
+
+// src/config/microfrontends-config/isomorphic/utils/generate-port.ts
+function generatePortFromName({
+  name,
+  minPort = 3e3,
+  maxPort = 8e3
+}) {
+  if (!name) {
+    throw new Error("Name is required to generate a port");
+  }
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) {
+    hash = (hash << 5) - hash + name.charCodeAt(i);
+    hash |= 0;
+  }
+  hash = Math.abs(hash);
+  const range = maxPort - minPort;
+  const port = minPort + hash % range;
+  return port;
+}
+
+// src/config/microfrontends-config/isomorphic/host.ts
+var Host = class {
+  constructor(hostConfig, options) {
+    if (typeof hostConfig === "string") {
+      ({
+        protocol: this.protocol,
+        host: this.host,
+        port: this.port
+      } = Host.parseUrl(hostConfig));
+    } else {
+      const { protocol = "https", host, port } = hostConfig;
+      this.protocol = protocol;
+      this.host = host;
+      this.port = port;
+    }
+    this.local = options?.isLocal;
+  }
+  static parseUrl(url, defaultProtocol = "https") {
+    let hostToParse = url;
+    if (!/^https?:\/\//.exec(hostToParse)) {
+      hostToParse = `${defaultProtocol}://${hostToParse}`;
+    }
+    const parsed = new URL(hostToParse);
+    if (!parsed.hostname) {
+      throw new Error(Host.getMicrofrontendsError(url, "requires a host"));
+    }
+    if (parsed.hash) {
+      throw new Error(
+        Host.getMicrofrontendsError(url, "cannot have a fragment")
+      );
+    }
+    if (parsed.username || parsed.password) {
+      throw new Error(
+        Host.getMicrofrontendsError(
+          url,
+          "cannot have authentication credentials (username and/or password)"
+        )
+      );
+    }
+    if (parsed.pathname !== "/") {
+      throw new Error(Host.getMicrofrontendsError(url, "cannot have a path"));
+    }
+    if (parsed.search) {
+      throw new Error(
+        Host.getMicrofrontendsError(url, "cannot have query parameters")
+      );
+    }
+    const protocol = parsed.protocol.slice(0, -1);
+    return {
+      protocol,
+      host: parsed.hostname,
+      port: parsed.port ? Number.parseInt(parsed.port, 10) : void 0
+    };
+  }
+  static getMicrofrontendsError(url, message) {
+    return `Microfrontends configuration error: the URL ${url} in your microfrontends.json ${message}.`;
+  }
+  isLocal() {
+    return this.local || this.host === "localhost" || this.host === "127.0.0.1";
+  }
+  toString() {
+    const url = this.toUrl();
+    return url.toString().replace(/\/$/, "");
+  }
+  toUrl() {
+    const url = `${this.protocol}://${this.host}${this.port ? `:${this.port}` : ""}`;
+    return new URL(url);
+  }
+};
+var LocalHost = class extends Host {
+  constructor({
+    appName,
+    local
+  }) {
+    const portOverride = process.env[MFE_APP_PORT_ENV];
+    if (portOverride) {
+      const overridePort = Number.parseInt(portOverride, 10);
+      if (!Number.isNaN(overridePort) && overridePort > 0 && overridePort < 65536) {
+        super({
+          protocol: "http",
+          host: "localhost",
+          port: overridePort
+        });
+        return;
+      }
+    }
+    let protocol;
+    let host;
+    let port;
+    if (typeof local === "number") {
+      port = local;
+    } else if (typeof local === "string") {
+      if (/^\d+$/.test(local)) {
+        port = Number.parseInt(local, 10);
+      } else {
+        const parsed = Host.parseUrl(local, "http");
+        protocol = parsed.protocol;
+        host = parsed.host;
+        port = parsed.port;
+      }
+    } else if (local) {
+      protocol = local.protocol;
+      host = local.host;
+      port = local.port;
+    }
+    super({
+      protocol: protocol ?? "http",
+      host: host ?? "localhost",
+      port: port ?? generatePortFromName({ name: appName })
+    });
+  }
+};
+
+// src/config/microfrontends-config/isomorphic/utils/hash-application-name.ts
+var import_md5 = __toESM(require("md5"), 1);
+function hashApplicationName(name) {
+  if (!name) {
+    throw new Error("Application name is required to generate hash");
+  }
+  return (0, import_md5.default)(name).substring(0, 6).padStart(6, "0");
+}
+
+// src/config/microfrontends-config/isomorphic/utils/generate-asset-prefix.ts
+var PREFIX = "vc-ap";
+function generateAssetPrefixFromName({
+  name
+}) {
+  if (!name) {
+    throw new Error("Name is required to generate an asset prefix");
+  }
+  return `${PREFIX}-${hashApplicationName(name)}`;
+}
+
+// src/config/microfrontends-config/isomorphic/utils/generate-automation-bypass-env-var-name.ts
+function generateAutomationBypassEnvVarName({
+  name
+}) {
+  return `AUTOMATION_BYPASS_${name.toUpperCase().replace(/[^a-zA-Z0-9]/g, "_")}`;
+}
+
 // src/config/microfrontends-config/isomorphic/validation.ts
 var import_path_to_regexp2 = require("path-to-regexp");
 var LIST_FORMATTER = new Intl.ListFormat("en", {
@@ -681,154 +870,6 @@ var validateConfigDefaultApplication = (applicationConfigsById) => {
   }
 };
 
-// src/config/microfrontends-config/isomorphic/utils/hash-application-name.ts
-var import_md5 = __toESM(require("md5"), 1);
-function hashApplicationName(name) {
-  if (!name) {
-    throw new Error("Application name is required to generate hash");
-  }
-  return (0, import_md5.default)(name).substring(0, 6).padStart(6, "0");
-}
-
-// src/config/microfrontends-config/isomorphic/utils/generate-asset-prefix.ts
-var PREFIX = "vc-ap";
-function generateAssetPrefixFromName({
-  name
-}) {
-  if (!name) {
-    throw new Error("Name is required to generate an asset prefix");
-  }
-  return `${PREFIX}-${hashApplicationName(name)}`;
-}
-
-// src/config/microfrontends-config/isomorphic/utils/generate-port.ts
-function generatePortFromName({
-  name,
-  minPort = 3e3,
-  maxPort = 8e3
-}) {
-  if (!name) {
-    throw new Error("Name is required to generate a port");
-  }
-  let hash = 0;
-  for (let i = 0; i < name.length; i++) {
-    hash = (hash << 5) - hash + name.charCodeAt(i);
-    hash |= 0;
-  }
-  hash = Math.abs(hash);
-  const range = maxPort - minPort;
-  const port = minPort + hash % range;
-  return port;
-}
-
-// src/config/microfrontends-config/isomorphic/host.ts
-var Host = class {
-  constructor(hostConfig, options) {
-    if (typeof hostConfig === "string") {
-      ({
-        protocol: this.protocol,
-        host: this.host,
-        port: this.port
-      } = Host.parseUrl(hostConfig));
-    } else {
-      const { protocol = "https", host, port } = hostConfig;
-      this.protocol = protocol;
-      this.host = host;
-      this.port = port;
-    }
-    this.local = options?.isLocal;
-  }
-  static parseUrl(url, defaultProtocol = "https") {
-    let hostToParse = url;
-    if (!/^https?:\/\//.exec(hostToParse)) {
-      hostToParse = `${defaultProtocol}://${hostToParse}`;
-    }
-    const parsed = new URL(hostToParse);
-    if (!parsed.hostname) {
-      throw new Error(Host.getMicrofrontendsError(url, "requires a host"));
-    }
-    if (parsed.hash) {
-      throw new Error(
-        Host.getMicrofrontendsError(url, "cannot have a fragment")
-      );
-    }
-    if (parsed.username || parsed.password) {
-      throw new Error(
-        Host.getMicrofrontendsError(
-          url,
-          "cannot have authentication credentials (username and/or password)"
-        )
-      );
-    }
-    if (parsed.pathname !== "/") {
-      throw new Error(Host.getMicrofrontendsError(url, "cannot have a path"));
-    }
-    if (parsed.search) {
-      throw new Error(
-        Host.getMicrofrontendsError(url, "cannot have query parameters")
-      );
-    }
-    const protocol = parsed.protocol.slice(0, -1);
-    return {
-      protocol,
-      host: parsed.hostname,
-      port: parsed.port ? Number.parseInt(parsed.port) : void 0
-    };
-  }
-  static getMicrofrontendsError(url, message) {
-    return `Microfrontends configuration error: the URL ${url} in your microfrontends.json ${message}.`;
-  }
-  isLocal() {
-    return this.local || this.host === "localhost" || this.host === "127.0.0.1";
-  }
-  toString() {
-    const url = this.toUrl();
-    return url.toString().replace(/\/$/, "");
-  }
-  toUrl() {
-    const url = `${this.protocol}://${this.host}${this.port ? `:${this.port}` : ""}`;
-    return new URL(url);
-  }
-};
-var LocalHost = class extends Host {
-  constructor({
-    appName,
-    local
-  }) {
-    let protocol;
-    let host;
-    let port;
-    if (typeof local === "number") {
-      port = local;
-    } else if (typeof local === "string") {
-      if (/^\d+$/.test(local)) {
-        port = Number.parseInt(local);
-      } else {
-        const parsed = Host.parseUrl(local, "http");
-        protocol = parsed.protocol;
-        host = parsed.host;
-        port = parsed.port;
-      }
-    } else if (local) {
-      protocol = local.protocol;
-      host = local.host;
-      port = local.port;
-    }
-    super({
-      protocol: protocol ?? "http",
-      host: host ?? "localhost",
-      port: port ?? generatePortFromName({ name: appName })
-    });
-  }
-};
-
-// src/config/microfrontends-config/isomorphic/utils/generate-automation-bypass-env-var-name.ts
-function generateAutomationBypassEnvVarName({
-  name
-}) {
-  return `AUTOMATION_BYPASS_${name.toUpperCase().replace(/[^a-zA-Z0-9]/g, "_")}`;
-}
-
 // src/config/microfrontends-config/isomorphic/application.ts
 var Application = class {
   constructor(name, {
@@ -909,9 +950,6 @@ var ChildApplication = class extends Application {
   }
 };
 
-// src/config/microfrontends-config/isomorphic/constants.ts
-var DEFAULT_LOCAL_PROXY_PORT = 3024;
-
 // src/config/microfrontends-config/isomorphic/index.ts
 var MicrofrontendConfigIsomorphic = class {
   constructor({
@@ -1030,9 +1068,17 @@ var MicrofrontendConfigIsomorphic = class {
     return this.defaultApplication;
   }
   /**
-   * Returns the configured port for the local proxy
+   * Returns the configured port for the local proxy.
+   * Can be overridden via MFE_LOCAL_PROXY_PORT environment variable.
    */
   getLocalProxyPort() {
+    const portOverride = process.env[MFE_LOCAL_PROXY_PORT_ENV];
+    if (portOverride) {
+      const port = Number.parseInt(portOverride, 10);
+      if (!Number.isNaN(port) && port > 0 && port < 65536) {
+        return port;
+      }
+    }
     return this.config.options?.localProxyPort ?? DEFAULT_LOCAL_PROXY_PORT;
   }
   toClientConfig(options) {
@@ -1070,23 +1116,78 @@ var MicrofrontendConfigIsomorphic = class {
   }
 };
 
-// src/config/microfrontends/server/index.ts
-var import_node_fs7 = __toESM(require("fs"), 1);
-var import_node_path8 = require("path");
+// src/config/microfrontends/utils/find-config.ts
+var import_node_fs = __toESM(require("fs"), 1);
+var import_node_path = require("path");
+
+// src/config/microfrontends/utils/get-config-file-name.ts
+var DEFAULT_CONFIGURATION_FILENAMES = [
+  "microfrontends.json",
+  "microfrontends.jsonc"
+];
+function getPossibleConfigurationFilenames({
+  customConfigFilename
+}) {
+  if (customConfigFilename) {
+    if (!customConfigFilename.endsWith(".json") && !customConfigFilename.endsWith(".jsonc")) {
+      throw new Error(
+        `Found VC_MICROFRONTENDS_CONFIG_FILE_NAME but the name is invalid. Received: ${customConfigFilename}. The file name must end with '.json' or '.jsonc'. It's also possible for the env var to include the path, eg microfrontends-dev.json or /path/to/microfrontends-dev.json.`
+      );
+    }
+    return Array.from(
+      /* @__PURE__ */ new Set([customConfigFilename, ...DEFAULT_CONFIGURATION_FILENAMES])
+    );
+  }
+  return DEFAULT_CONFIGURATION_FILENAMES;
+}
+
+// src/config/microfrontends/utils/find-config.ts
+function findConfig({
+  dir,
+  customConfigFilename
+}) {
+  for (const filename of getPossibleConfigurationFilenames({
+    customConfigFilename
+  })) {
+    const maybeConfig = (0, import_node_path.join)(dir, filename);
+    if (import_node_fs.default.existsSync(maybeConfig)) {
+      return maybeConfig;
+    }
+  }
+  return null;
+}
+
+// src/config/microfrontends/utils/find-package-root.ts
+var import_node_fs2 = __toESM(require("fs"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
+var PACKAGE_JSON = "package.json";
+function findPackageRoot(startDir) {
+  let currentDir = startDir || process.cwd();
+  while (currentDir !== import_node_path2.default.parse(currentDir).root) {
+    const pkgJsonPath = import_node_path2.default.join(currentDir, PACKAGE_JSON);
+    if (import_node_fs2.default.existsSync(pkgJsonPath)) {
+      return currentDir;
+    }
+    currentDir = import_node_path2.default.dirname(currentDir);
+  }
+  throw new Error(
+    `The root of the package that contains the \`package.json\` file for the \`${startDir}\` directory could not be found.`
+  );
+}
 
 // src/config/microfrontends/utils/find-repository-root.ts
-var import_node_fs = __toESM(require("fs"), 1);
-var import_node_path = __toESM(require("path"), 1);
+var import_node_fs3 = __toESM(require("fs"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
 var GIT_DIRECTORY = ".git";
 function hasGitDirectory(dir) {
-  const gitPath = import_node_path.default.join(dir, GIT_DIRECTORY);
-  return import_node_fs.default.existsSync(gitPath) && import_node_fs.default.statSync(gitPath).isDirectory();
+  const gitPath = import_node_path3.default.join(dir, GIT_DIRECTORY);
+  return import_node_fs3.default.existsSync(gitPath) && import_node_fs3.default.statSync(gitPath).isDirectory();
 }
 function hasPnpmWorkspaces(dir) {
-  return import_node_fs.default.existsSync(import_node_path.default.join(dir, "pnpm-workspace.yaml"));
+  return import_node_fs3.default.existsSync(import_node_path3.default.join(dir, "pnpm-workspace.yaml"));
 }
 function hasPackageJson(dir) {
-  return import_node_fs.default.existsSync(import_node_path.default.join(dir, "package.json"));
+  return import_node_fs3.default.existsSync(import_node_path3.default.join(dir, "package.json"));
 }
 function findRepositoryRoot(startDir) {
   if (process.env.NX_WORKSPACE_ROOT) {
@@ -1094,14 +1195,14 @@ function findRepositoryRoot(startDir) {
   }
   let currentDir = startDir || process.cwd();
   let lastPackageJsonDir = null;
-  while (currentDir !== import_node_path.default.parse(currentDir).root) {
+  while (currentDir !== import_node_path3.default.parse(currentDir).root) {
     if (hasGitDirectory(currentDir) || hasPnpmWorkspaces(currentDir)) {
       return currentDir;
     }
     if (hasPackageJson(currentDir)) {
       lastPackageJsonDir = currentDir;
     }
-    currentDir = import_node_path.default.dirname(currentDir);
+    currentDir = import_node_path3.default.dirname(currentDir);
   }
   if (lastPackageJsonDir) {
     return lastPackageJsonDir;
@@ -1111,34 +1212,88 @@ function findRepositoryRoot(startDir) {
   );
 }
 
-// src/config/microfrontends/utils/infer-microfrontends-location.ts
-var import_node_path2 = require("path");
-var import_node_fs2 = require("fs");
-var import_jsonc_parser2 = require("jsonc-parser");
-var import_fast_glob = __toESM(require("fast-glob"), 1);
-
-// src/config/microfrontends/utils/get-config-file-name.ts
-var DEFAULT_CONFIGURATION_FILENAMES = [
-  "microfrontends.json",
-  "microfrontends.jsonc"
-];
-function getPossibleConfigurationFilenames({
-  customConfigFilename
-}) {
-  if (customConfigFilename) {
-    if (!customConfigFilename.endsWith(".json") && !customConfigFilename.endsWith(".jsonc")) {
-      throw new Error(
-        `Found VC_MICROFRONTENDS_CONFIG_FILE_NAME but the name is invalid. Received: ${customConfigFilename}. The file name must end with '.json' or '.jsonc'. It's also possible for the env var to include the path, eg microfrontends-dev.json or /path/to/microfrontends-dev.json.`
+// src/config/microfrontends/utils/get-application-context.ts
+var import_node_fs4 = __toESM(require("fs"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
+function getApplicationContext(opts) {
+  if (opts?.appName) {
+    logger.debug(
+      "[MFE Config] Application name from appName parameter:",
+      opts.appName
+    );
+    return { name: opts.appName };
+  }
+  if (process.env.VERCEL_PROJECT_NAME) {
+    logger.debug(
+      "[MFE Config] Application name from VERCEL_PROJECT_NAME:",
+      process.env.VERCEL_PROJECT_NAME
+    );
+    return {
+      name: process.env.VERCEL_PROJECT_NAME,
+      projectName: process.env.VERCEL_PROJECT_NAME
+    };
+  }
+  if (process.env.NX_TASK_TARGET_PROJECT) {
+    logger.debug(
+      "[MFE Config] Application name from NX_TASK_TARGET_PROJECT:",
+      process.env.NX_TASK_TARGET_PROJECT
+    );
+    return {
+      name: process.env.NX_TASK_TARGET_PROJECT,
+      packageJsonName: process.env.NX_TASK_TARGET_PROJECT
+    };
+  }
+  try {
+    const vercelProjectJsonPath = import_node_fs4.default.readFileSync(
+      import_node_path4.default.join(opts?.packageRoot || ".", ".vercel", "project.json"),
+      "utf-8"
+    );
+    const projectJson = JSON.parse(vercelProjectJsonPath);
+    if (projectJson.projectName) {
+      logger.debug(
+        "[MFE Config] Application name from .vercel/project.json:",
+        projectJson.projectName
       );
+      return {
+        name: projectJson.projectName,
+        projectName: projectJson.projectName
+      };
     }
-    return Array.from(
-      /* @__PURE__ */ new Set([customConfigFilename, ...DEFAULT_CONFIGURATION_FILENAMES])
+  } catch (_) {
+  }
+  try {
+    const packageJsonString = import_node_fs4.default.readFileSync(
+      import_node_path4.default.join(opts?.packageRoot || ".", "package.json"),
+      "utf-8"
+    );
+    const packageJson = JSON.parse(packageJsonString);
+    if (!packageJson.name) {
+      throw new MicrofrontendError(
+        `package.json file missing required field "name"`,
+        {
+          type: "packageJson",
+          subtype: "missing_field_name",
+          source: "@vercel/microfrontends/next"
+        }
+      );
+    }
+    logger.debug(
+      "[MFE Config] Application name from package.json:",
+      packageJson.name
     );
+    return { name: packageJson.name, packageJsonName: packageJson.name };
+  } catch (err) {
+    throw MicrofrontendError.handle(err, {
+      fileName: "package.json"
+    });
   }
-  return DEFAULT_CONFIGURATION_FILENAMES;
 }
 
 // src/config/microfrontends/utils/infer-microfrontends-location.ts
+var import_node_fs5 = require("fs");
+var import_node_path5 = require("path");
+var import_fast_glob = __toESM(require("fast-glob"), 1);
+var import_jsonc_parser2 = require("jsonc-parser");
 var configCache = {};
 function findPackageWithMicrofrontendsConfig({
   repositoryRoot,
@@ -1146,6 +1301,10 @@ function findPackageWithMicrofrontendsConfig({
   customConfigFilename
 }) {
   const applicationName = applicationContext.name;
+  logger.debug(
+    "[MFE Config] Searching repository for configs containing application:",
+    applicationName
+  );
   try {
     const microfrontendsJsonPaths = import_fast_glob.default.globSync(
       `**/{${getPossibleConfigurationFilenames({ customConfigFilename }).join(",")}}`,
@@ -1157,28 +1316,21 @@ function findPackageWithMicrofrontendsConfig({
         ignore: ["**/node_modules/**", "**/.git/**"]
       }
     );
+    logger.debug(
+      "[MFE Config] Found",
+      microfrontendsJsonPaths.length,
+      "config file(s) in repository"
+    );
     const matchingPaths = [];
     for (const microfrontendsJsonPath of microfrontendsJsonPaths) {
-      try {
-        const microfrontendsJsonContent = (0, import_node_fs2.readFileSync)(
-          microfrontendsJsonPath,
-          "utf-8"
-        );
-        const microfrontendsJson = (0, import_jsonc_parser2.parse)(microfrontendsJsonContent);
-        if (microfrontendsJson.applications[applicationName]) {
-          matchingPaths.push(microfrontendsJsonPath);
-        } else {
-          for (const [_, app] of Object.entries(
-            microfrontendsJson.applications
-          )) {
-            if (app.packageName === applicationName) {
-              matchingPaths.push(microfrontendsJsonPath);
-            }
-          }
-        }
-      } catch (error2) {
+      if (doesApplicationExistInConfig(microfrontendsJsonPath, applicationName)) {
+        matchingPaths.push(microfrontendsJsonPath);
       }
     }
+    logger.debug(
+      "[MFE Config] Total matching config files:",
+      matchingPaths.length
+    );
     if (matchingPaths.length > 1) {
       throw new MicrofrontendError(
         `Found multiple \`microfrontends.json\` files in the repository referencing the application "${applicationName}", but only one is allowed.
@@ -1187,6 +1339,34 @@ ${matchingPaths.join("\n  \u2022 ")}`,
       );
     }
     if (matchingPaths.length === 0) {
+      if (repositoryRoot && doesMisplacedConfigExist(
+        repositoryRoot,
+        applicationName,
+        customConfigFilename
+      )) {
+        logger.debug(
+          "[MFE Config] Found misplaced config in wrong .vercel directory in repository"
+        );
+        const misplacedConfigPath = (0, import_node_path5.join)(
+          repositoryRoot,
+          ".vercel",
+          customConfigFilename || "microfrontends.json"
+        );
+        throw new MicrofrontendError(
+          `Unable to automatically infer the location of the \`microfrontends.json\` file.
+
+A microfrontends config was found in the \`.vercel\` directory at the repository root: ${misplacedConfigPath}
+However, in a monorepo, the config file should be placed in the \`.vercel\` directory in your application directory instead.
+
+To fix this:
+1. If using \`vercel link\`, run it with \`vercel link --repo\` to handle monorepos, or run \`vercel microfrontends pull --cwd=<application-directory>\` to make sure it pulls the \`microfrontends.json\` file to the correct location
+2. If manually defined, move the config file to the \`.vercel\` directory in your application
+3. Alternatively, set the VC_MICROFRONTENDS_CONFIG environment variable to the correct path
+
+For more information, see: https://vercel.com/docs/cli/project-linking`,
+          { type: "config", subtype: "inference_failed" }
+        );
+      }
       let additionalErrorMessage = "";
       if (microfrontendsJsonPaths.length > 0) {
         if (!applicationContext.projectName) {
@@ -1211,7 +1391,7 @@ If you suspect this is thrown in error, please reach out to the Vercel team.`,
       );
     }
     const [packageJsonPath] = matchingPaths;
-    return (0, import_node_path2.dirname)(packageJsonPath);
+    return (0, import_node_path5.dirname)(packageJsonPath);
   } catch (error2) {
     if (error2 instanceof MicrofrontendError) {
       throw error2;
@@ -1234,53 +1414,76 @@ function inferMicrofrontendsLocation(opts) {
   configCache[cacheKey] = result;
   return result;
 }
-
-// src/config/microfrontends/utils/is-monorepo.ts
-var import_node_fs3 = __toESM(require("fs"), 1);
-var import_node_path3 = __toESM(require("path"), 1);
-
-// src/bin/logger.ts
-function debug(...args) {
-  if (process.env.MFE_DEBUG) {
-    console.log(...args);
+function existsSync(path7) {
+  try {
+    (0, import_node_fs5.statSync)(path7);
+    return true;
+  } catch (_) {
+    return false;
   }
 }
-function info(...args) {
-  console.log(...args);
-}
-function warn(...args) {
-  console.warn(...args);
+function doesMisplacedConfigExist(repositoryRoot, applicationName, customConfigFilename) {
+  logger.debug(
+    "[MFE Config] Looking for misplaced config in wrong .vercel directory"
+  );
+  const misplacedConfigPath = (0, import_node_path5.join)(
+    repositoryRoot,
+    ".vercel",
+    customConfigFilename || "microfrontends.json"
+  );
+  return existsSync(misplacedConfigPath) && doesApplicationExistInConfig(misplacedConfigPath, applicationName);
 }
-function error(...args) {
-  console.error(...args);
+function doesApplicationExistInConfig(microfrontendsJsonPath, applicationName) {
+  try {
+    const microfrontendsJsonContent = (0, import_node_fs5.readFileSync)(
+      microfrontendsJsonPath,
+      "utf-8"
+    );
+    const microfrontendsJson = (0, import_jsonc_parser2.parse)(microfrontendsJsonContent);
+    if (microfrontendsJson.applications[applicationName]) {
+      logger.debug(
+        "[MFE Config] Found application in config:",
+        microfrontendsJsonPath
+      );
+      return true;
+    }
+    for (const [_, app] of Object.entries(microfrontendsJson.applications)) {
+      if (app.packageName === applicationName) {
+        logger.debug(
+          "[MFE Config] Found application via packageName in config:",
+          microfrontendsJsonPath
+        );
+        return true;
+      }
+    }
+  } catch (error2) {
+    logger.debug("[MFE Config] Error checking application in config:", error2);
+  }
+  return false;
 }
-var logger = {
-  debug,
-  info,
-  warn,
-  error
-};
 
 // src/config/microfrontends/utils/is-monorepo.ts
+var import_node_fs6 = __toESM(require("fs"), 1);
+var import_node_path6 = __toESM(require("path"), 1);
 function isMonorepo({
   repositoryRoot
 }) {
   try {
-    if (import_node_fs3.default.existsSync(import_node_path3.default.join(repositoryRoot, "pnpm-workspace.yaml"))) {
+    if (import_node_fs6.default.existsSync(import_node_path6.default.join(repositoryRoot, "pnpm-workspace.yaml"))) {
       return true;
     }
-    if (import_node_fs3.default.existsSync(import_node_path3.default.join(repositoryRoot, "vlt-workspaces.json"))) {
+    if (import_node_fs6.default.existsSync(import_node_path6.default.join(repositoryRoot, "vlt-workspaces.json"))) {
       return true;
     }
-    if (process.env.NX_WORKSPACE_ROOT === import_node_path3.default.resolve(repositoryRoot)) {
+    if (process.env.NX_WORKSPACE_ROOT === import_node_path6.default.resolve(repositoryRoot)) {
       return true;
     }
-    const packageJsonPath = import_node_path3.default.join(repositoryRoot, "package.json");
-    if (!import_node_fs3.default.existsSync(packageJsonPath)) {
+    const packageJsonPath = import_node_path6.default.join(repositoryRoot, "package.json");
+    if (!import_node_fs6.default.existsSync(packageJsonPath)) {
       return false;
     }
     const packageJson = JSON.parse(
-      import_node_fs3.default.readFileSync(packageJsonPath, "utf-8")
+      import_node_fs6.default.readFileSync(packageJsonPath, "utf-8")
     );
     return packageJson.workspaces !== void 0;
   } catch (error2) {
@@ -1289,99 +1492,6 @@ function isMonorepo({
   }
 }
 
-// src/config/microfrontends/utils/find-package-root.ts
-var import_node_fs4 = __toESM(require("fs"), 1);
-var import_node_path4 = __toESM(require("path"), 1);
-var PACKAGE_JSON = "package.json";
-function findPackageRoot(startDir) {
-  let currentDir = startDir || process.cwd();
-  while (currentDir !== import_node_path4.default.parse(currentDir).root) {
-    const pkgJsonPath = import_node_path4.default.join(currentDir, PACKAGE_JSON);
-    if (import_node_fs4.default.existsSync(pkgJsonPath)) {
-      return currentDir;
-    }
-    currentDir = import_node_path4.default.dirname(currentDir);
-  }
-  throw new Error(
-    `The root of the package that contains the \`package.json\` file for the \`${startDir}\` directory could not be found.`
-  );
-}
-
-// src/config/microfrontends/utils/find-config.ts
-var import_node_fs5 = __toESM(require("fs"), 1);
-var import_node_path5 = require("path");
-function findConfig({
-  dir,
-  customConfigFilename
-}) {
-  for (const filename of getPossibleConfigurationFilenames({
-    customConfigFilename
-  })) {
-    const maybeConfig = (0, import_node_path5.join)(dir, filename);
-    if (import_node_fs5.default.existsSync(maybeConfig)) {
-      return maybeConfig;
-    }
-  }
-  return null;
-}
-
-// src/config/microfrontends/utils/get-application-context.ts
-var import_node_fs6 = __toESM(require("fs"), 1);
-var import_node_path6 = __toESM(require("path"), 1);
-function getApplicationContext(opts) {
-  if (opts?.appName) {
-    return { name: opts.appName };
-  }
-  if (process.env.VERCEL_PROJECT_NAME) {
-    return {
-      name: process.env.VERCEL_PROJECT_NAME,
-      projectName: process.env.VERCEL_PROJECT_NAME
-    };
-  }
-  if (process.env.NX_TASK_TARGET_PROJECT) {
-    return {
-      name: process.env.NX_TASK_TARGET_PROJECT,
-      packageJsonName: process.env.NX_TASK_TARGET_PROJECT
-    };
-  }
-  try {
-    const vercelProjectJsonPath = import_node_fs6.default.readFileSync(
-      import_node_path6.default.join(opts?.packageRoot || ".", ".vercel", "project.json"),
-      "utf-8"
-    );
-    const projectJson = JSON.parse(vercelProjectJsonPath);
-    if (projectJson.projectName) {
-      return {
-        name: projectJson.projectName,
-        projectName: projectJson.projectName
-      };
-    }
-  } catch (_) {
-  }
-  try {
-    const packageJsonString = import_node_fs6.default.readFileSync(
-      import_node_path6.default.join(opts?.packageRoot || ".", "package.json"),
-      "utf-8"
-    );
-    const packageJson = JSON.parse(packageJsonString);
-    if (!packageJson.name) {
-      throw new MicrofrontendError(
-        `package.json file missing required field "name"`,
-        {
-          type: "packageJson",
-          subtype: "missing_field_name",
-          source: "@vercel/microfrontends/next"
-        }
-      );
-    }
-    return { name: packageJson.name, packageJsonName: packageJson.name };
-  } catch (err) {
-    throw MicrofrontendError.handle(err, {
-      fileName: "package.json"
-    });
-  }
-}
-
 // src/config/microfrontends/server/utils/get-output-file-path.ts
 var import_node_path7 = __toESM(require("path"), 1);
 
@@ -1395,8 +1505,8 @@ function getOutputFilePath() {
 }
 
 // src/config/microfrontends/server/validation.ts
-var import_jsonc_parser3 = require("jsonc-parser");
 var import_ajv = require("ajv");
+var import_jsonc_parser3 = require("jsonc-parser");
 
 // schema/schema.json
 var schema_default = {
@@ -1424,9 +1534,7 @@ var schema_default = {
           description: "Optional configuration options for the microfrontend."
         }
       },
-      required: [
-        "applications"
-      ],
+      required: ["applications"],
       additionalProperties: false,
       description: "The microfrontends configuration schema. See https://vercel.com/docs/microfrontends/configuration."
     },
@@ -1463,19 +1571,14 @@ var schema_default = {
           description: "Development configuration for the default application."
         }
       },
-      required: [
-        "development"
-      ],
+      required: ["development"],
       additionalProperties: false
     },
     DefaultDevelopment: {
       type: "object",
       properties: {
         local: {
-          type: [
-            "number",
-            "string"
-          ],
+          type: ["number", "string"],
           description: "A local port number or host that this application runs on when it is running locally. If passing a string, include the protocol (optional), host (required) and port (optional).\n\nExamples of valid values: 8080, my.localhost.me, my.localhost.me:8080, https://my.localhost.me, https://my.localhost.me:8080.\n\nThe default value is http://localhost:<port> where port is a stable, unique port number (based on the application name).\n\nSee https://vercel.com/docs/microfrontends/local-development."
         },
         task: {
@@ -1487,9 +1590,7 @@ var schema_default = {
           description: "Fallback for local development, could point to any environment. This is required for the default app. This value is used as the fallback for child apps as well if they do not have a fallback.\n\nIf passing a string, include the protocol (optional), host (required) and port (optional). For example: `https://this.ismyhost:8080`. If omitted, the protocol defaults to HTTPS. If omitted, the port defaults to `80` for HTTP and `443` for HTTPS.\n\nSee https://vercel.com/docs/microfrontends/local-development."
         }
       },
-      required: [
-        "fallback"
-      ],
+      required: ["fallback"],
       additionalProperties: false
     },
     ChildApplication: {
@@ -1512,19 +1613,14 @@ var schema_default = {
           description: "The name of the asset prefix to use instead of the auto-generated name.\n\nThe asset prefix is used to prefix all paths to static assets, such as JS, CSS, or images that are served by a specific application. It is necessary to ensure there are no conflicts with other applications on the same domain.\n\nAn auto-generated asset prefix of the form `vc-ap-<hash>` is used when this field is not provided.\n\nWhen this field is provided, `/${assetPrefix}/:path*` must also be added to the list of paths in the `routing` field. Changing the asset prefix after a microfrontend application has already been deployed is not a forwards and backwards compatible change, and the asset prefix should be added to the `routing` field and deployed before setting the `assetPrefix` field.\n\nThe default value is the auto-generated asset prefix of the form `vc-ap-<hash>`.\n\nSee https://vercel.com/docs/microfrontends/path-routing#asset-prefix."
         }
       },
-      required: [
-        "routing"
-      ],
+      required: ["routing"],
       additionalProperties: false
     },
     ChildDevelopment: {
       type: "object",
       properties: {
         local: {
-          type: [
-            "number",
-            "string"
-          ],
+          type: ["number", "string"],
           description: "A local port number or host that this application runs on when it is running locally. If passing a string, include the protocol (optional), host (required) and port (optional).\n\nExamples of valid values: 8080, my.localhost.me, my.localhost.me:8080, https://my.localhost.me, https://my.localhost.me:8080.\n\nThe default value is http://localhost:<port> where port is a stable, unique port number (based on the application name).\n\nSee https://vercel.com/docs/microfrontends/local-development."
         },
         task: {
@@ -1564,9 +1660,7 @@ var schema_default = {
           description: "A list of path expressions that are routed to this application. See https://vercel.com/docs/microfrontends/path-routing#supported-path-expressions."
         }
       },
-      required: [
-        "paths"
-      ],
+      required: ["paths"],
       additionalProperties: false,
       description: "A group of paths that is routed to this application."
     },
@@ -1745,7 +1839,13 @@ var MicrofrontendsServer = class {
     filePath,
     cookies
   } = {}) {
+    logger.debug("[MFE Config] Starting config inference", {
+      appName,
+      directory: directory || process.cwd(),
+      filePath
+    });
     if (filePath) {
+      logger.debug("[MFE Config] Using explicit filePath:", filePath);
       return MicrofrontendsServer.fromFile({
         filePath,
         cookies
@@ -1753,16 +1853,25 @@ var MicrofrontendsServer = class {
     }
     try {
       const packageRoot = findPackageRoot(directory);
+      logger.debug("[MFE Config] Package root:", packageRoot);
       const applicationContext = getApplicationContext({
         appName,
         packageRoot
       });
+      logger.debug("[MFE Config] Application context:", applicationContext);
       const customConfigFilename = process.env.VC_MICROFRONTENDS_CONFIG_FILE_NAME;
+      if (customConfigFilename) {
+        logger.debug(
+          "[MFE Config] Custom config filename from VC_MICROFRONTENDS_CONFIG_FILE_NAME:",
+          customConfigFilename
+        );
+      }
       const maybeConfig = findConfig({
         dir: packageRoot,
         customConfigFilename
       });
       if (maybeConfig) {
+        logger.debug("[MFE Config] Config found at package root:", maybeConfig);
         return MicrofrontendsServer.fromFile({
           filePath: maybeConfig,
           cookies
@@ -1770,42 +1879,78 @@ var MicrofrontendsServer = class {
       }
       const repositoryRoot = findRepositoryRoot();
       const isMonorepo2 = isMonorepo({ repositoryRoot });
+      logger.debug(
+        "[MFE Config] Repository root:",
+        repositoryRoot,
+        "Is monorepo:",
+        isMonorepo2
+      );
       const configFromEnv = process.env.VC_MICROFRONTENDS_CONFIG;
       if (typeof configFromEnv === "string") {
+        logger.debug(
+          "[MFE Config] Checking VC_MICROFRONTENDS_CONFIG:",
+          configFromEnv
+        );
         const maybeConfigFromEnv = (0, import_node_path8.resolve)(packageRoot, configFromEnv);
         if (maybeConfigFromEnv) {
+          logger.debug(
+            "[MFE Config] Config loaded from VC_MICROFRONTENDS_CONFIG:",
+            maybeConfigFromEnv
+          );
           return MicrofrontendsServer.fromFile({
             filePath: maybeConfigFromEnv,
             cookies
           });
         }
       } else {
+        const vercelDir = (0, import_node_path8.join)(packageRoot, ".vercel");
+        logger.debug(
+          "[MFE Config] Searching for config in .vercel directory:",
+          vercelDir
+        );
         const maybeConfigFromVercel = findConfig({
-          dir: (0, import_node_path8.join)(packageRoot, ".vercel"),
+          dir: vercelDir,
           customConfigFilename
         });
         if (maybeConfigFromVercel) {
+          logger.debug(
+            "[MFE Config] Config found in .vercel directory:",
+            maybeConfigFromVercel
+          );
           return MicrofrontendsServer.fromFile({
             filePath: maybeConfigFromVercel,
             cookies
           });
         }
         if (isMonorepo2) {
+          logger.debug(
+            "[MFE Config] Inferring microfrontends location in monorepo for application:",
+            applicationContext.name
+          );
           const defaultPackage = inferMicrofrontendsLocation({
             repositoryRoot,
             applicationContext,
             customConfigFilename
           });
+          logger.debug(
+            "[MFE Config] Inferred package location:",
+            defaultPackage
+          );
           const maybeConfigFromDefault = findConfig({
             dir: defaultPackage,
             customConfigFilename
           });
           if (maybeConfigFromDefault) {
+            logger.debug(
+              "[MFE Config] Config found in inferred package:",
+              maybeConfigFromDefault
+            );
             return MicrofrontendsServer.fromFile({
               filePath: maybeConfigFromDefault,
               cookies
             });
           }
+          logger.debug("[MFE Config] No config found in inferred package");
         }
       }
       throw new MicrofrontendError(
@@ -1831,8 +1976,13 @@ var MicrofrontendsServer = class {
     cookies
   }) {
     try {
+      logger.debug("[MFE Config] Reading config from file:", filePath);
       const configJson = import_node_fs7.default.readFileSync(filePath, "utf-8");
       const config = MicrofrontendsServer.validate(configJson);
+      logger.debug(
+        "[MFE Config] Config loaded with applications:",
+        Object.keys(config.applications)
+      );
       return new MicrofrontendsServer({
         config,
         overrides: cookies ? parseOverrides(cookies) : void 0
@@ -2583,6 +2733,11 @@ var LocalProxy = class {
         `The following apps passed via --local-apps are not in the microfrontends config: ${unknownApps.join(", ")} (microfrontends config contains: ${Array.from(allApps).join(", ")})`
       );
     }
+    if (process.env[MFE_APP_PORT_ENV] && localApps.length > 1) {
+      throw new Error(
+        `${MFE_APP_PORT_ENV} cannot be used when multiple applications are running locally. You have ${localApps.length} local apps: ${localApps.join(", ")}. Either run a single app locally or remove the ${MFE_APP_PORT_ENV} environment variable.`
+      );
+    }
   }
   startServer() {
     const httpServer = http.createServer(
@@ -2854,10 +3009,23 @@ function formatProxyTarget(target) {
 var import_node_process = require("process");
 
 // src/utils/mfe-port.ts
-var import_node_path9 = __toESM(require("path"), 1);
 var import_node_fs8 = __toESM(require("fs"), 1);
+var import_node_path9 = __toESM(require("path"), 1);
+var MFE_APP_PORT_ENV2 = "MFE_APP_PORT";
 function mfePort(packageDir) {
   const { name: appName, version } = getPackageJson(packageDir);
+  const portOverride = process.env[MFE_APP_PORT_ENV2];
+  if (portOverride) {
+    const port = Number.parseInt(portOverride, 10);
+    if (!Number.isNaN(port) && port > 0 && port < 65536) {
+      return {
+        name: appName,
+        version,
+        port,
+        overridden: true
+      };
+    }
+  }
   try {
     const result = loadConfig({ packageDir, appName });
     const { port } = result;
@@ -2890,14 +3058,16 @@ function loadConfig({
 
 // src/bin/port.ts
 function displayPort() {
+  delete process.env.MFE_DEBUG;
   const portInfo = mfePort((0, import_node_process.cwd)());
   header(portInfo);
   logger.info(portInfo.port);
 }
-function header({ name, version, port }) {
+function header({ name, version, port, overridden }) {
+  const portSource = overridden ? `${port} (override via ${MFE_APP_PORT_ENV2})` : port;
   logger.error(`
   \u25B2 ${name}@${version}
-    \xB7 setting port to ${port}
+    \xB7 setting port to ${portSource}
   `);
 }