@vercel/microfrontends 2.1.3 → 2.2.1

package/dist/bin/cli.cjs

@@ -30,7 +30,7 @@ var import_env = require("@next/env");
 // package.json
 var package_default = {
   name: "@vercel/microfrontends",
-  version: "2.1.3",
+  version: "2.2.1",
   private: false,
   description: "Defines configuration and utilities for microfrontends development",
   keywords: [
@@ -1117,10 +1117,32 @@ var import_node_fs2 = require("fs");
 var import_jsonc_parser2 = require("jsonc-parser");
 var import_fast_glob = __toESM(require("fast-glob"), 1);
 
+// 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/microfrontends/utils/get-config-file-name.ts
 var DEFAULT_CONFIGURATION_FILENAMES = [
-  "microfrontends.jsonc",
-  "microfrontends.json"
+  "microfrontends.json",
+  "microfrontends.jsonc"
 ];
 function getPossibleConfigurationFilenames({
   customConfigFilename
@@ -1128,7 +1150,7 @@ function getPossibleConfigurationFilenames({
   if (customConfigFilename) {
     if (!customConfigFilename.endsWith(".json") && !customConfigFilename.endsWith(".jsonc")) {
       throw new Error(
-        `The VC_MICROFRONTENDS_CONFIG_FILE_NAME environment variable must end with '.json' or '.jsonc'. Received: ${customConfigFilename}`
+        `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(
@@ -1146,6 +1168,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,6 +1183,11 @@ 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 {
@@ -1166,19 +1197,31 @@ function findPackageWithMicrofrontendsConfig({
         );
         const microfrontendsJson = (0, import_jsonc_parser2.parse)(microfrontendsJsonContent);
         if (microfrontendsJson.applications[applicationName]) {
+          logger.debug(
+            "[MFE Config] Found application in config:",
+            microfrontendsJsonPath
+          );
           matchingPaths.push(microfrontendsJsonPath);
         } else {
           for (const [_, app] of Object.entries(
             microfrontendsJson.applications
           )) {
             if (app.packageName === applicationName) {
+              logger.debug(
+                "[MFE Config] Found application via packageName in config:",
+                microfrontendsJsonPath
+              );
               matchingPaths.push(microfrontendsJsonPath);
             }
           }
         }
-      } catch (error) {
+      } catch (error2) {
       }
     }
+    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.
@@ -1212,9 +1255,9 @@ 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);
-  } catch (error) {
-    if (error instanceof MicrofrontendError) {
-      throw error;
+  } catch (error2) {
+    if (error2 instanceof MicrofrontendError) {
+      throw error2;
     }
     return null;
   }
@@ -1259,8 +1302,8 @@ function isMonorepo({
       import_node_fs3.default.readFileSync(packageJsonPath, "utf-8")
     );
     return packageJson.workspaces !== void 0;
-  } catch (error) {
-    console.error("Error determining if repository is a monorepo", error);
+  } catch (error2) {
+    logger.error("Error determining if repository is a monorepo", error2);
     return false;
   }
 }
@@ -1306,15 +1349,18 @@ var import_node_fs6 = __toESM(require("fs"), 1);
 var import_node_path6 = __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
@@ -1327,6 +1373,7 @@ function getApplicationContext(opts) {
     );
     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
@@ -1350,6 +1397,7 @@ function getApplicationContext(opts) {
         }
       );
     }
+    logger.debug("[MFE Config] Application name from package.json:", packageJson.name);
     return { name: packageJson.name, packageJsonName: packageJson.name };
   } catch (err) {
     throw MicrofrontendError.handle(err, {
@@ -1383,38 +1431,28 @@ var schema_default = {
       type: "object",
       properties: {
         $schema: {
-          type: "string"
+          type: "string",
+          description: "See https://openapi.vercel.sh/microfrontends.json."
         },
         version: {
           type: "string",
-          const: "1"
-        },
-        options: {
-          $ref: "#/definitions/Options"
+          const: "1",
+          description: "The version of the microfrontends config schema."
         },
         applications: {
           $ref: "#/definitions/ApplicationRouting",
-          description: "Mapping of application names to the routes that they host. Only needs to be defined in the application that owns the primary microfrontend domain"
+          description: "Mapping of Vercel project names to their microfrontend configurations."
+        },
+        options: {
+          $ref: "#/definitions/Options",
+          description: "Optional configuration options for the microfrontend."
         }
       },
       required: [
         "applications"
       ],
-      additionalProperties: false
-    },
-    Options: {
-      type: "object",
-      properties: {
-        disableOverrides: {
-          type: "boolean",
-          description: "If you want to disable the overrides for the site. For example, if you are managing rewrites between applications externally, you may wish to disable the overrides on the toolbar as they will have no effect."
-        },
-        localProxyPort: {
-          type: "number",
-          description: "The port number used by the local proxy server.\n\nThe default is `3024`."
-        }
-      },
-      additionalProperties: false
+      additionalProperties: false,
+      description: "The microfrontends configuration schema. See https://vercel.com/docs/microfrontends/configuration."
     },
     ApplicationRouting: {
       type: "object",
@@ -1422,8 +1460,9 @@ var schema_default = {
         $ref: "#/definitions/Application"
       },
       propertyNames: {
-        description: "The unique identifier for a Microfrontend Application.\n\nMust match the Vercel project name.\n\nNote: If this name does not also match the name used to run the application, (e.g. the `name` from the `package.json`), then the `packageName` field should be set."
-      }
+        description: "The Vercel project name of the microfrontend application.\n\nNote: If this name does not also match the name `name` from the `package.json`, set `packageName` with the name used in `package.json`.\n\nSee https://vercel.com/docs/microfrontends/configuration#application-naming."
+      },
+      description: "Mapping of Vercel project names to their microfrontend configurations."
     },
     Application: {
       anyOf: [
@@ -1433,14 +1472,15 @@ var schema_default = {
         {
           $ref: "#/definitions/ChildApplication"
         }
-      ]
+      ],
+      description: "The configuration for a microfrontend application. There must always be one default application."
     },
     DefaultApplication: {
       type: "object",
       properties: {
         packageName: {
           type: "string",
-          description: "The name used to run the application, e.g. the `name` field in the `package.json`.\n\nThis is used by the local proxy to map the application config to the locally running app.\n\nThis is only necessary when the application name does not match the `name` used in `package.json`."
+          description: "The name used to run the application, e.g. the `name` field in the `package.json`.\n\nThis is used by the local proxy to map the application config to the locally running app.\n\nThis is only necessary when the application name does not match the `name` used in `package.json`.\n\nSee https://vercel.com/docs/microfrontends/configuration#application-naming."
         },
         development: {
           $ref: "#/definitions/DefaultDevelopment",
@@ -1460,15 +1500,15 @@ var schema_default = {
             "number",
             "string"
           ],
-          description: "A local port number or host string that this application runs on when it is running locally. If passing a string, include the protocol (optional), host (required) and port (optional). For example: `https://this.ismyhost:8080`. If omitted, the protocol defaults to HTTP. If omitted, the port defaults to a unique, but stable (based on the application name) number.\n\nExamples of valid values:\n- 8080\n- my.localhost.me\n- my.localhost.me:8080\n- https://my.localhost.me\n- https://my.localhost.me:8080"
+          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: {
           type: "string",
-          description: "Optional task to run when starting the development server. Should reference a script in the package.json of the application."
+          description: 'The task to run when starting the development server. Should reference a script in the package.json of the application.\n\nThe default value is "dev".\n\nSee https://vercel.com/docs/microfrontends/local-development.'
         },
         fallback: {
           type: "string",
-          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."
+          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: [
@@ -1481,7 +1521,7 @@ var schema_default = {
       properties: {
         packageName: {
           type: "string",
-          description: "The name used to run the application, e.g. the `name` field in the `package.json`.\n\nThis is used by the local proxy to map the application config to the locally running app.\n\nThis is only necessary when the application name does not match the `name` used in `package.json`."
+          description: "The name used to run the application, e.g. the `name` field in the `package.json`.\n\nThis is used by the local proxy to map the application config to the locally running app.\n\nThis is only necessary when the application name does not match the `name` used in `package.json`.\n\nSee https://vercel.com/docs/microfrontends/configuration#application-naming."
         },
         development: {
           $ref: "#/definitions/ChildDevelopment",
@@ -1489,11 +1529,11 @@ var schema_default = {
         },
         routing: {
           $ref: "#/definitions/Routing",
-          description: "Groups of path expressions that are routed to this application."
+          description: "Groups of path expressions that are routed to this application.\n\nSee https://vercel.com/docs/microfrontends/path-routing."
         },
         assetPrefix: {
           type: "string",
-          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."
+          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: [
@@ -1509,15 +1549,15 @@ var schema_default = {
             "number",
             "string"
           ],
-          description: "A local port number or host string that this application runs on when it is running locally. If passing a string, include the protocol (optional), host (required) and port (optional). For example: `https://this.ismyhost:8080`. If omitted, the protocol defaults to HTTP. If omitted, the port defaults to a unique, but stable (based on the application name) number.\n\nExamples of valid values:\n- 8080\n- my.localhost.me\n- my.localhost.me:8080\n- https://my.localhost.me\n- https://my.localhost.me:8080"
+          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: {
           type: "string",
-          description: "Optional task to run when starting the development server. Should reference a script in the package.json of the application."
+          description: 'The task to run when starting the development server. Should reference a script in the package.json of the application.\n\nThe default value is "dev".\n\nSee https://vercel.com/docs/microfrontends/local-development.'
         },
         fallback: {
           type: "string",
-          description: "Fallback for local development, could point to any environment. This is optional for child apps. If not provided, the fallback of the default app will be used.\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."
+          description: "Fallback for local development, could point to any environment. If not provided for child apps, the fallback of the default app will be used.\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."
         }
       },
       additionalProperties: false
@@ -1526,29 +1566,46 @@ var schema_default = {
       type: "array",
       items: {
         $ref: "#/definitions/PathGroup"
-      }
+      },
+      description: "A list of path groups that are routed to this application."
     },
     PathGroup: {
       type: "object",
       properties: {
         group: {
           type: "string",
-          description: "Optional group name for the paths"
+          description: "Group name for the paths."
         },
         flag: {
           type: "string",
-          description: "flag name that can be used to enable/disable all paths in the group"
+          description: "The name of the feature flag that controls routing for this group of paths. See https://vercel.com/docs/microfrontends/path-routing#routing-changes-safely-with-flags."
         },
         paths: {
           type: "array",
           items: {
             type: "string"
-          }
+          },
+          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"
       ],
+      additionalProperties: false,
+      description: "A group of paths that is routed to this application."
+    },
+    Options: {
+      type: "object",
+      properties: {
+        disableOverrides: {
+          type: "boolean",
+          description: "If you want to disable the overrides for the site. For example, if you are managing rewrites between applications externally, you may wish to disable the overrides on the toolbar as they will have no effect.\n\nSee https://vercel.com/docs/microfrontends/managing-microfrontends/vercel-toolbar#routing-overrides."
+        },
+        localProxyPort: {
+          type: "number",
+          description: "The port number used by the local proxy server.\n\nThe default value is 3024.\n\nSee https://vercel.com/docs/microfrontends/local-development."
+        }
+      },
       additionalProperties: false
     }
   }
@@ -1567,19 +1624,19 @@ function formatAjvErrors(errors) {
     return [];
   }
   const errorMessages = [];
-  for (const error of errors) {
-    if (error.instancePath === "" && (error.keyword === "anyOf" || error.keyword === "required" && error.params.missingProperty === "partOf")) {
+  for (const error2 of errors) {
+    if (error2.instancePath === "" && (error2.keyword === "anyOf" || error2.keyword === "required" && error2.params.missingProperty === "partOf")) {
       continue;
     }
-    const instancePath = error.instancePath.slice(1);
+    const instancePath = error2.instancePath.slice(1);
     const formattedInstancePath = instancePath === "" ? "at the root" : `in field ${instancePath}`;
-    if (error.keyword === "required" && error.params.missingProperty === "routing" && instancePath.split("/").length === 2) {
+    if (error2.keyword === "required" && error2.params.missingProperty === "routing" && instancePath.split("/").length === 2) {
       errorMessages.push(
         `Unable to infer if ${instancePath} is the default app or a child app. This usually means that there is another error in the configuration.`
       );
-    } else if (error.keyword === "anyOf" && instancePath.split("/").length > 2) {
+    } else if (error2.keyword === "anyOf" && instancePath.split("/").length > 2) {
       const anyOfErrors = errors.filter(
-        (e) => e.instancePath === error.instancePath && e.keyword !== "anyOf"
+        (e) => e.instancePath === error2.instancePath && e.keyword !== "anyOf"
       );
       if (anyOfErrors.every((e) => e.keyword === "type")) {
         const allowedTypes = LIST_FORMATTER2.format(
@@ -1595,13 +1652,13 @@ function formatAjvErrors(errors) {
           `Invalid field for ${instancePath}. Possible error messages are ${LIST_FORMATTER2.format(anyOfErrors.map((e) => e.message ?? ""))}`
         );
       }
-    } else if (error.keyword === "additionalProperties" && !(error.params.additionalProperty === "routing" && instancePath.split("/").length === 2)) {
+    } else if (error2.keyword === "additionalProperties" && !(error2.params.additionalProperty === "routing" && instancePath.split("/").length === 2)) {
       errorMessages.push(
-        `Property '${error.params.additionalProperty}' is not allowed ${formattedInstancePath}`
+        `Property '${error2.params.additionalProperty}' is not allowed ${formattedInstancePath}`
       );
-    } else if (error.keyword === "required") {
+    } else if (error2.keyword === "required") {
       errorMessages.push(
-        `Property '${error.params.missingProperty}' is required ${formattedInstancePath}`
+        `Property '${error2.params.missingProperty}' is required ${formattedInstancePath}`
       );
     }
   }
@@ -1614,8 +1671,8 @@ function validateSchema(configString) {
   const isValid = validate(parsedConfig);
   if (!isValid) {
     throw new MicrofrontendError(
-      `Invalid microfrontends config:${formatAjvErrors(validate.errors).map((error) => `
- - ${error}`).join(
+      `Invalid microfrontends config:${formatAjvErrors(validate.errors).map((error2) => `
+ - ${error2}`).join(
         ""
       )}
 
@@ -1712,7 +1769,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
@@ -1720,16 +1783,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
@@ -1737,42 +1809,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(
@@ -1798,8 +1906,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
@@ -2293,7 +2406,7 @@ var ProxyRequestRouter = class {
     if (target)
       return target;
     const defaultHost = this.getDefaultHost(config);
-    console.log(
+    logger.debug(
       ` ${path7} - Did not match any routes. Routing to default app: ${formatProxyTarget(defaultHost)}`
     );
     return { path: path7, ...defaultHost };
@@ -2310,7 +2423,7 @@ var ProxyRequestRouter = class {
       const target = this.getApplicationTarget(application);
       if (middlewareMfeZone) {
         if (middlewareMfeZone === application.name) {
-          console.log(
+          logger.debug(
             ` ${path7} - Routing to ${formatProxyTarget(target)} according to 'x-vercel-mfe-zone' header`
           );
           return { path: path7, ...target };
@@ -2335,19 +2448,19 @@ var ProxyRequestRouter = class {
               } else if (mfeFlagValue === false) {
                 continue;
               } else {
-                console.log(
+                logger.debug(
                   "Routing group is behind flag. Routing to default app to check flag via middleware."
                 );
                 if (!this.isDefaultAppLocal()) {
                   const defaultApp = this.getDefaultHost(this.config);
-                  console.error(
+                  logger.error(
                     `'${path7}' is a flagged path, but the default application is not running locally. Using '${defaultApp.hostname}' to handle this request.`
                   );
                 }
                 return null;
               }
             }
-            console.log(
+            logger.debug(
               ` ${path7} - Matched ${childPath}. Routing to ${formatProxyTarget(target)}`
             );
             return { path: path7, ...target };
@@ -2356,7 +2469,7 @@ var ProxyRequestRouter = class {
       }
     }
     if (middlewareMfeZone) {
-      console.error(
+      logger.error(
         `A request contained 'x-vercel-mfe-zone: ${middlewareMfeZone}', but no application was found with that name.`
       );
     }
@@ -2378,7 +2491,7 @@ var ProxyRequestRouter = class {
     for (const rewrite of rewrites) {
       for (const assetPrefix of assetPrefixes) {
         if ((0, import_path_to_regexp3.pathToRegexp)(`/${assetPrefix}${rewrite}`).test(pathname)) {
-          console.log(
+          logger.debug(
             ` ${pathname} - Matched asset prefix. Routing to ${formatProxyTarget(target)}`
           );
           return {
@@ -2410,7 +2523,7 @@ var ProxyRequestRouter = class {
     if (!refererApp) {
       return null;
     }
-    console.log(
+    logger.debug(
       ` ${refererURL.pathname} - Routing nextjs stack frame request to ${formatProxyTarget(refererApp)}`
     );
     return {
@@ -2425,13 +2538,13 @@ var ProxyRequestRouter = class {
     }
     const localApp = this.getArbitraryLocalApp();
     if (!localApp) {
-      console.error(
+      logger.error(
         ` ${url.pathname} - No locally running application to route request to`
       );
       return null;
     }
     const target = this.getApplicationTarget(localApp);
-    console.log(
+    logger.debug(
       ` ${url.pathname} - Routing nextjs source map request to randomly selected local application: ${formatProxyTarget(target)}`
     );
     return {
@@ -2449,7 +2562,7 @@ var ProxyRequestRouter = class {
     }
     const imageUrl = url.searchParams.get("url");
     if (!imageUrl) {
-      console.error(
+      logger.error(
         ` ${url.pathname}?${url.search} - No url parameter found in _next/image request`
       );
       return null;
@@ -2464,7 +2577,7 @@ var ProxyRequestRouter = class {
     if (!imageApp) {
       return null;
     }
-    console.log(
+    logger.debug(
       ` ${url.pathname}?${url.search} - Routing nextjs image request to ${formatProxyTarget(imageApp)}`
     );
     return {
@@ -2509,7 +2622,7 @@ var LocalProxy = class {
       res.end(
         `Error proxying request to ${formatProxyTarget(target)}. Is the server running locally on port ${target.port}?`
       );
-      console.error(
+      logger.error(
         `Error proxying request for ${formatProxyTarget(target)}: `,
         err
       );
@@ -2565,7 +2678,7 @@ var LocalProxy = class {
           headers
         });
       } catch (err) {
-        console.error("Error proxying ws: ", err);
+        logger.error("Error proxying ws: ", err);
       }
     });
     httpServer.listen(this.proxyPort, () => {
@@ -2662,7 +2775,7 @@ var LocalProxy = class {
       });
       req.pipe(proxyReq);
       proxyReq.on("error", (err) => {
-        console.error("Proxy request error: ", err);
+        logger.error("Proxy request error: ", err);
         res.writeHead(500, { "Content-Type": "text/plain" });
         res.end(
           `Error proxying request for ${target.application} to ${hostname}:${port}${path7}`
@@ -2735,49 +2848,52 @@ var LocalProxy = class {
         });
       }
     }
-    console.log(`
+    logger.info(`
 \u25B2 Microfrontends Proxy (${package_default.version}) Started`);
-    console.log(`  - Proxy URL: http://localhost:${this.proxyPort}`);
+    logger.info(`  - Proxy URL: http://localhost:${this.proxyPort}`);
     if (this.configFilePath) {
-      console.log(`  - Config: ${this.configFilePath}`);
+      logger.info(`  - Config: ${this.configFilePath}`);
     }
     if (localApps.length > 0) {
-      console.log("  - Local Applications:");
+      logger.info("  - Local Applications:");
       const displayLocalApps = localApps.length > 5 ? [
         ...localApps.slice(0, 5),
         { name: `... and ${localApps.length - 5} more`, port: void 0 }
       ] : localApps;
       for (const app of displayLocalApps) {
         if (app.port !== void 0) {
-          console.log(`    \u2022 ${app.name} (port ${app.port})`);
+          logger.info(`    \u2022 ${app.name} (port ${app.port})`);
         } else {
-          console.log(`    \u2022 ${app.name}`);
+          logger.info(`    \u2022 ${app.name}`);
         }
       }
     }
     if (fallbackApps.length > 0) {
-      console.log("  - Fallback Applications:");
+      logger.info("  - Fallback Applications:");
       const displayFallbackApps = fallbackApps.length > 5 ? [
         ...fallbackApps.slice(0, 5),
         { name: `... and ${fallbackApps.length - 5} more`, fallback: "" }
       ] : fallbackApps;
       for (const app of displayFallbackApps) {
         if (app.fallback) {
-          console.log(`    \u2022 ${app.name} \u2192 ${app.fallback}`);
+          logger.info(`    \u2022 ${app.name} \u2192 ${app.fallback}`);
         } else {
-          console.log(`    \u2022 ${app.name}`);
+          logger.info(`    \u2022 ${app.name}`);
         }
       }
     }
     if (localApps.length === 0 && fallbackApps.length === 0) {
-      console.log("  - No applications configured\n");
+      logger.info("  - No applications configured\n");
     }
     if (localApps.length > 0) {
-      console.log(
+      logger.info(
         "\nRequests directly to the ports of these applications may be automatically\nredirected to this proxy. Set the MFE_DISABLE_LOCAL_PROXY_REWRITE=1\nenvironment variable to disable this behavior."
       );
     }
-    console.log(`
+    logger.info(
+      "\nTo debug routing, set an environment variable MFE_DEBUG=1,\nor enable the debug option when calling withMicrofrontends.\nThis will print out all routing information to the console.\n"
+    );
+    logger.info(`
 ${"\u2500".repeat(50)}
 `);
   }
@@ -2854,12 +2970,13 @@ function loadConfig({
 
 // src/bin/port.ts
 function displayPort() {
+  delete process.env.MFE_DEBUG;
   const portInfo = mfePort((0, import_node_process.cwd)());
   header(portInfo);
-  console.log(portInfo.port);
+  logger.info(portInfo.port);
 }
 function header({ name, version, port }) {
-  console.error(`
+  logger.error(`
   \u25B2 ${name}@${version}
     \xB7 setting port to ${port}
   `);