@vercel/microfrontends 1.0.1-canary.5 → 1.1.1-canary.0

package/dist/bin/cli.cjs

@@ -29,7 +29,7 @@ var import_commander = require("commander");
 // package.json
 var package_default = {
   name: "@vercel/microfrontends",
-  version: "1.0.1-canary.5",
+  version: "1.1.1-canary.0",
   private: false,
   description: "Defines configuration and utilities for microfrontends development",
   keywords: [
@@ -418,10 +418,13 @@ var validateConfigPaths = (applicationConfigsById) => {
     }
   }
   if (errors.length) {
-    throw new MicrofrontendError(`Invalid paths: ${errors.join(", ")}`, {
-      type: "config",
-      subtype: "conflicting_paths"
-    });
+    throw new MicrofrontendError(
+      `Invalid paths: ${errors.join(", ")}. See supported paths in the documentation https://vercel.com/docs/microfrontends/path-routing#supported-path-expressions.`,
+      {
+        type: "config",
+        subtype: "conflicting_paths"
+      }
+    );
   }
 };
 var PATH_DEFAULT_PATTERN = "[^\\/#\\?]+?";
@@ -536,9 +539,40 @@ var validateDeprecatedFields = (config) => {
         `Application '${applicationId}' cannot contain deprecated field 'production'. Use 'development.fallback' instead.`
       );
     }
-    if (application.development?.local) {
+    if (application.development?.localPort) {
       errors.push(
-        `Application '${applicationId}' cannot contain deprecated field 'development.local'. Use 'developement.localPort' instead.`
+        `Application '${applicationId}' cannot contain deprecated field 'development.localPort'. Use 'developement.local' instead.`
+      );
+    }
+    if (application.development?.fallback && typeof application.development.fallback !== "string") {
+      const fallback = application.development.fallback;
+      let asString = fallback.host;
+      if (fallback.protocol) {
+        asString = `${fallback.protocol}://${asString}`;
+      }
+      if (fallback.port) {
+        asString = `${asString}:${fallback.port}`;
+      }
+      errors.push(
+        `Application '${applicationId}' requires a string (not an object) for the 'development.fallback' field. Please set 'development.fallback' to '${asString}'.`
+      );
+    }
+    if (application.development?.local && typeof application.development.local !== "string" && typeof application.development.local !== "number") {
+      const local = application.development.local;
+      let asString;
+      if (local.port && !local.protocol && !local.host) {
+        asString = String(local.port);
+      } else {
+        asString = local.host ?? "localhost";
+        if (local.protocol) {
+          asString = `${local.protocol}://${asString}`;
+        }
+        if (local.port) {
+          asString = `${asString}:${local.port}`;
+        }
+      }
+      errors.push(
+        `Application '${applicationId}' requires a string or number (not an object) for the 'development.local' field. Please set 'development.local' to '${asString}'.`
       );
     }
   }
@@ -602,10 +636,10 @@ var Host = class {
     }
     this.local = options?.isLocal;
   }
-  static parseUrl(url) {
+  static parseUrl(url, defaultProtocol = "https") {
     let hostToParse = url;
     if (!/^https?:\/\//.exec(hostToParse)) {
-      hostToParse = `https://${hostToParse}`;
+      hostToParse = `${defaultProtocol}://${hostToParse}`;
     }
     const parsed = new URL(hostToParse);
     if (!parsed.hostname) {
@@ -658,12 +692,39 @@ var LocalHost = class extends Host {
   constructor({
     appName,
     localPort,
-    ...hostConfig
+    local
   }) {
-    const host = hostConfig.host ?? "localhost";
-    const port = localPort ?? hostConfig.port ?? generatePortFromName({ name: appName });
-    const protocol = hostConfig.protocol ?? "http";
-    super({ protocol, host, port });
+    if (localPort && local) {
+      throw new Error(
+        `Microfrontends configuration error: '${appName}' has both the 'development.local' and 'development.localPort' fields set. Please remove the 'development.localPort' field and ensure the 'development.local' field has the correct port.`
+      );
+    }
+    let protocol;
+    let host;
+    let port;
+    if (localPort) {
+      port = localPort;
+    } else 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 })
+    });
   }
 };
 
@@ -679,7 +740,7 @@ var Application = class {
       local: new LocalHost({
         appName: name,
         localPort: app.development?.localPort,
-        ...app.development?.local
+        local: app.development?.local
       }),
       fallback: app.development?.fallback ? new Host(app.development.fallback) : void 0
     };
@@ -689,6 +750,7 @@ var Application = class {
       this.fallback = new Host(app.production);
     }
     this.projectId = app.projectId ?? app.vercel?.projectId;
+    this.packageName = app.packageName;
     this.overrides = overrides?.environment ? {
       environment: new Host(overrides.environment)
     } : void 0;
@@ -973,10 +1035,12 @@ var MicrofrontendConfigIsomorphic = class {
     ].filter(Boolean);
   }
   getApplication(name) {
-    if (this.defaultApplication?.name === name) {
+    if (this.defaultApplication?.name === name || this.defaultApplication?.packageName === name) {
       return this.defaultApplication;
     }
-    const app = this.childApplications[name];
+    const app = this.childApplications[name] || Object.values(this.childApplications).find(
+      (child) => child.packageName === name
+    );
     if (!app) {
       throw new MicrofrontendError(
         `Could not find microfrontends configuration for application "${name}"`,
@@ -1434,9 +1498,7 @@ var schema_default = {
           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"
         }
       },
-      required: [
-        "applications"
-      ],
+      required: ["applications"],
       additionalProperties: false
     },
     Options: {
@@ -1489,7 +1551,7 @@ var schema_default = {
         $ref: "#/definitions/Application"
       },
       propertyNames: {
-        description: "The unique identifier for a Microfrontend Application. Must match the `name` field of the application's `package.json`."
+        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."
       }
     },
     Application: {
@@ -1511,7 +1573,12 @@ var schema_default = {
         },
         projectId: {
           type: "string",
-          description: "Vercel project ID"
+          description: "Vercel project ID, only required if the application name / id is different to the Vercel project name.",
+          deprecated: "Instead, the application id should match the Vercel project name."
+        },
+        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`."
         },
         production: {
           $ref: "#/definitions/HostConfig",
@@ -1531,9 +1598,7 @@ var schema_default = {
           description: "Vercel project ID"
         }
       },
-      required: [
-        "projectId"
-      ],
+      required: ["projectId"],
       additionalProperties: false
     },
     HostConfig: {
@@ -1541,10 +1606,7 @@ var schema_default = {
       properties: {
         protocol: {
           type: "string",
-          enum: [
-            "http",
-            "https"
-          ],
+          enum: ["http", "https"],
           description: "The protocol to be used for the connection.\n- `http`: Hypertext Transfer Protocol (HTTP).\n- `https`: Secure Hypertext Transfer Protocol (HTTPS).\n\n*"
         },
         host: {
@@ -1556,21 +1618,30 @@ var schema_default = {
           description: "The port number to be used for the connection. Common values include `80` for HTTP and `443` for HTTPS."
         }
       },
-      required: [
-        "host"
-      ],
+      required: ["host"],
       additionalProperties: false
     },
     Development: {
       type: "object",
       properties: {
         local: {
-          $ref: "#/definitions/LocalHostConfig",
-          deprecated: "This is being replaced by the `localPort` field below."
+          anyOf: [
+            {
+              type: "number"
+            },
+            {
+              type: "string"
+            },
+            {
+              $ref: "#/definitions/LocalHostConfig"
+            }
+          ],
+          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\n\nPassing a LocalHostConfig is deprecated and will go away soon, please pass a number or string."
         },
         localPort: {
           type: "number",
-          description: "The local port number that this application runs on when it is running locally. Common values include `80` for HTTP and `443` for HTTPS."
+          description: "The local port number that this application runs on when it is running locally. Common values include `80` for HTTP and `443` for HTTPS. If omitted, the port defaults to a unique, but stable (based on the application name) number.",
+          deprecated: "Please set the port with the 'local' field instead."
         },
         fallback: {
           anyOf: [
@@ -1581,7 +1652,7 @@ var schema_default = {
               type: "string"
             }
           ],
-          description: "Fallback for local development, could be a host config that points to any environment. If this is not provided, or the application is not running - requests to the application in local development will error.\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 this is not provided, or the application is not running - requests to the application in local development will error.\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\nPassing a HostConfig is deprecated and will go away soon, please pass a string."
         },
         task: {
           type: "string",
@@ -1600,10 +1671,7 @@ var schema_default = {
         },
         protocol: {
           type: "string",
-          enum: [
-            "http",
-            "https"
-          ],
+          enum: ["http", "https"],
           description: "The protocol to be used for the connection.\n- `http`: Hypertext Transfer Protocol (HTTP).\n- `https`: Secure Hypertext Transfer Protocol (HTTPS).\n\n*"
         },
         port: {
@@ -1621,7 +1689,12 @@ var schema_default = {
         },
         projectId: {
           type: "string",
-          description: "Vercel project ID"
+          description: "Vercel project ID, only required if the application name / id is different to the Vercel project name.",
+          deprecated: "Instead, the application id should match the Vercel project name."
+        },
+        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`."
         },
         production: {
           $ref: "#/definitions/HostConfig",
@@ -1635,9 +1708,7 @@ var schema_default = {
           description: "Groups of path expressions that are routed to this application."
         }
       },
-      required: [
-        "routing"
-      ],
+      required: ["routing"],
       additionalProperties: false
     },
     Routing: {
@@ -1664,9 +1735,7 @@ var schema_default = {
           }
         }
       },
-      required: [
-        "paths"
-      ],
+      required: ["paths"],
       additionalProperties: false
     },
     ChildConfig: {
@@ -1687,9 +1756,7 @@ var schema_default = {
           description: "Applications that only serve a subset of the microfrontend routes only need to reference the name of the primary application that owns the full microfrontends configuration."
         }
       },
-      required: [
-        "partOf"
-      ],
+      required: ["partOf"],
       additionalProperties: false
     }
   }
@@ -1967,7 +2034,9 @@ var ProxyRequestRouter = class {
     return this.getApplicationTarget(defaultApp);
   }
   getApplicationTarget(application) {
-    const useDev = this.localApps.includes(application.name);
+    const useDev = this.localApps.find(
+      (name) => name === application.name || name === application.packageName
+    );
     let applicationName = application.name;
     let host = useDev ? application.development.local : application.fallback;
     if (application.overrides?.environment?.host) {
@@ -2181,7 +2250,12 @@ var ProxyRequestRouter = class {
     } : null;
   }
   isDefaultAppLocal() {
-    return this.localApps.includes(this.config.getDefaultApplication().name);
+    const defaultApp = this.config.getDefaultApplication();
+    return Boolean(
+      this.localApps.find(
+        (name) => name === defaultApp.name || name === defaultApp.packageName
+      )
+    );
   }
 };
 var LocalProxy = class {
@@ -2330,7 +2404,8 @@ function extractMfeFlagValue(path7) {
 function stringAsBoolean(value) {
   if (value === "true") {
     return true;
-  } else if (value === "false") {
+  }
+  if (value === "false") {
     return false;
   }
   return void 0;

package/dist/config.cjs

@@ -298,10 +298,13 @@ var validateConfigPaths = (applicationConfigsById) => {
     }
   }
   if (errors.length) {
-    throw new MicrofrontendError(`Invalid paths: ${errors.join(", ")}`, {
-      type: "config",
-      subtype: "conflicting_paths"
-    });
+    throw new MicrofrontendError(
+      `Invalid paths: ${errors.join(", ")}. See supported paths in the documentation https://vercel.com/docs/microfrontends/path-routing#supported-path-expressions.`,
+      {
+        type: "config",
+        subtype: "conflicting_paths"
+      }
+    );
   }
 };
 var PATH_DEFAULT_PATTERN = "[^\\/#\\?]+?";
@@ -416,9 +419,40 @@ var validateDeprecatedFields = (config) => {
         `Application '${applicationId}' cannot contain deprecated field 'production'. Use 'development.fallback' instead.`
       );
     }
-    if (application.development?.local) {
+    if (application.development?.localPort) {
+      errors.push(
+        `Application '${applicationId}' cannot contain deprecated field 'development.localPort'. Use 'developement.local' instead.`
+      );
+    }
+    if (application.development?.fallback && typeof application.development.fallback !== "string") {
+      const fallback = application.development.fallback;
+      let asString = fallback.host;
+      if (fallback.protocol) {
+        asString = `${fallback.protocol}://${asString}`;
+      }
+      if (fallback.port) {
+        asString = `${asString}:${fallback.port}`;
+      }
+      errors.push(
+        `Application '${applicationId}' requires a string (not an object) for the 'development.fallback' field. Please set 'development.fallback' to '${asString}'.`
+      );
+    }
+    if (application.development?.local && typeof application.development.local !== "string" && typeof application.development.local !== "number") {
+      const local = application.development.local;
+      let asString;
+      if (local.port && !local.protocol && !local.host) {
+        asString = String(local.port);
+      } else {
+        asString = local.host ?? "localhost";
+        if (local.protocol) {
+          asString = `${local.protocol}://${asString}`;
+        }
+        if (local.port) {
+          asString = `${asString}:${local.port}`;
+        }
+      }
       errors.push(
-        `Application '${applicationId}' cannot contain deprecated field 'development.local'. Use 'developement.localPort' instead.`
+        `Application '${applicationId}' requires a string or number (not an object) for the 'development.local' field. Please set 'development.local' to '${asString}'.`
       );
     }
   }
@@ -482,10 +516,10 @@ var Host = class {
     }
     this.local = options?.isLocal;
   }
-  static parseUrl(url) {
+  static parseUrl(url, defaultProtocol = "https") {
     let hostToParse = url;
     if (!/^https?:\/\//.exec(hostToParse)) {
-      hostToParse = `https://${hostToParse}`;
+      hostToParse = `${defaultProtocol}://${hostToParse}`;
     }
     const parsed = new URL(hostToParse);
     if (!parsed.hostname) {
@@ -538,12 +572,39 @@ var LocalHost = class extends Host {
   constructor({
     appName,
     localPort,
-    ...hostConfig
+    local
   }) {
-    const host = hostConfig.host ?? "localhost";
-    const port = localPort ?? hostConfig.port ?? generatePortFromName({ name: appName });
-    const protocol = hostConfig.protocol ?? "http";
-    super({ protocol, host, port });
+    if (localPort && local) {
+      throw new Error(
+        `Microfrontends configuration error: '${appName}' has both the 'development.local' and 'development.localPort' fields set. Please remove the 'development.localPort' field and ensure the 'development.local' field has the correct port.`
+      );
+    }
+    let protocol;
+    let host;
+    let port;
+    if (localPort) {
+      port = localPort;
+    } else 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 })
+    });
   }
 };
 
@@ -559,7 +620,7 @@ var Application = class {
       local: new LocalHost({
         appName: name,
         localPort: app.development?.localPort,
-        ...app.development?.local
+        local: app.development?.local
       }),
       fallback: app.development?.fallback ? new Host(app.development.fallback) : void 0
     };
@@ -569,6 +630,7 @@ var Application = class {
       this.fallback = new Host(app.production);
     }
     this.projectId = app.projectId ?? app.vercel?.projectId;
+    this.packageName = app.packageName;
     this.overrides = overrides?.environment ? {
       environment: new Host(overrides.environment)
     } : void 0;
@@ -734,10 +796,12 @@ var MicrofrontendConfigIsomorphic = class {
     ].filter(Boolean);
   }
   getApplication(name) {
-    if (this.defaultApplication?.name === name) {
+    if (this.defaultApplication?.name === name || this.defaultApplication?.packageName === name) {
       return this.defaultApplication;
     }
-    const app = this.childApplications[name];
+    const app = this.childApplications[name] || Object.values(this.childApplications).find(
+      (child) => child.packageName === name
+    );
     if (!app) {
       throw new MicrofrontendError(
         `Could not find microfrontends configuration for application "${name}"`,