@vercel/microfrontends

Version:

Defines configuration and utilities for microfrontends development

1 lines • 68.6 kB

Source Map (JSON)

{"version":3,"sources":["../../src/next/testing/index.ts","../../src/config/microfrontends-config/isomorphic/index.ts","../../src/config/errors.ts","../../src/config/microfrontends-config/utils/get-config-from-env.ts","../../src/config/schema/utils/is-default-app.ts","../../src/config/microfrontends-config/client/index.ts","../../src/config/overrides/constants.ts","../../src/config/overrides/is-override-cookie.ts","../../src/config/overrides/get-override-from-cookie.ts","../../src/config/overrides/parse-overrides.ts","../../src/config/microfrontends-config/isomorphic/validation.ts","../../src/config/microfrontends-config/isomorphic/utils/generate-asset-prefix.ts","../../src/config/microfrontends-config/isomorphic/utils/generate-port.ts","../../src/config/microfrontends-config/isomorphic/host.ts","../../src/config/microfrontends-config/isomorphic/utils/generate-automation-bypass-env-var-name.ts","../../src/config/microfrontends-config/isomorphic/application.ts","../../src/config/microfrontends-config/isomorphic/constants.ts"],"sourcesContent":["import { readFileSync } from 'node:fs';\nimport {\n type NextFetchEvent,\n NextRequest,\n type MiddlewareConfig,\n} from 'next/server.js';\nimport { match, pathToRegexp } from 'path-to-regexp';\nimport { parse } from 'jsonc-parser';\nimport { MicrofrontendConfigIsomorphic } from '../../config/microfrontends-config/isomorphic';\nimport { DefaultApplication } from '../../config/microfrontends-config/isomorphic/application';\nimport type { Config } from '../../config/schema/types';\n\n/** Replaces path wildcards (if they exist) with synthesized paths. */\nexport function expandWildcards(path: string): string[] {\n if (path.includes('/:path*') || path.includes('/:slug*')) {\n return [\n path === '/:path*' || path === '/:slug*'\n ? '/'\n : path.replace('/:path*', '').replace('/:slug*', ''),\n path.replace('/:path*', '/foo').replace('/:slug*', '/foo'),\n path.replace('/:path*', '/foo/bar').replace('/:slug*', '/foo/bar'),\n ];\n }\n if (path.includes('/:path+') || path.includes('/:slug+')) {\n return [\n path.replace('/:path+', '/foo').replace('/:slug+', '/foo'),\n path.replace('/:path+', '/foo/bar').replace('/:slug+', '/foo/bar'),\n ];\n }\n if (path.includes('/:path') || path.includes('/:slug')) {\n return [path.replace('/:path', '/foo').replace('/:slug', '/foo')];\n }\n return [path];\n}\n\nexport function loadMicrofrontendConfigForEdge(\n path: string,\n): MicrofrontendConfigIsomorphic {\n // NOTE: It's necessary to read and parse this file manually because tests that\n // run in `@edge-runtime/jest-environment` will fail since the AJV validation\n // from the @vercel/microfrontends package violates the rules by\n // using eval.\n const rawMfConfig = parse(readFileSync(path, 'utf-8')) as Config;\n return new MicrofrontendConfigIsomorphic({\n config: rawMfConfig,\n });\n}\n\nexport function getAllChildApplicationNames(\n mfConfig: MicrofrontendConfigIsomorphic,\n): string[] {\n return mfConfig.getChildApplications().map((app) => app.name);\n}\n\nexport function getLaunchedPathsForApp(\n mfConfig: MicrofrontendConfigIsomorphic,\n appName: string,\n): string[] {\n const app = mfConfig.getApplication(appName);\n if (app instanceof DefaultApplication) {\n return [];\n }\n\n return [\n `/${app.getAssetPrefix()}/_next/static`,\n ...app.routing\n .filter((group) => !group.flag)\n .flatMap((group) => group.paths.flatMap(expandWildcards)),\n ];\n}\n\nexport function getFlaggedPathsForApp(\n mfConfig: MicrofrontendConfigIsomorphic,\n appName: string,\n): string[] {\n const app = mfConfig.getApplication(appName);\n if (app instanceof DefaultApplication) {\n return [];\n }\n\n return app.routing\n .filter((group) => Boolean(group.flag))\n .flatMap((group) => group.paths.flatMap(expandWildcards));\n}\n\n/**\n * Returns a list of examples for all paths in microfrontends.json.\n */\nexport function getAllMicrofrontendPaths(\n mfConfig: MicrofrontendConfigIsomorphic,\n): string[] {\n return mfConfig.getChildApplications().flatMap((app) => {\n return app.routing.flatMap((group) => group.paths.flatMap(expandWildcards));\n });\n}\n\nfunction urlMatches(\n middlewareConfig: MiddlewareConfig,\n path: string,\n doNotMatchWithHasOrMissing?: boolean,\n): boolean {\n if (!middlewareConfig.matcher) {\n return false;\n }\n // This is based off\n // https://github.com/vercel/next.js/blob/4835be182b88f67f282c30db4278c30fe9e5b483/packages/next/src/build/analysis/get-page-static-info.ts#L324\n const matchers = Array.isArray(middlewareConfig.matcher)\n ? middlewareConfig.matcher\n : [middlewareConfig.matcher];\n for (let matcher of matchers) {\n matcher = typeof matcher === 'string' ? { source: matcher } : matcher;\n if (match(matcher.source)(path)) {\n if (doNotMatchWithHasOrMissing && (matcher.has || matcher.missing)) {\n return false;\n }\n return true;\n }\n }\n return false;\n}\n\n/**\n * A test to ensure that middleware is configured to work correctly with\n * microfrontends. Passing this test does NOT guarantee middleware is set up\n * correctly, but this should find many common problems. This should only be run\n * on the application marked as \"default\" in the microfrontend config. If a\n * configuration issue is found, this will throw an exception (this ensures it\n * works with any test framework).\n *\n * For example, if a microfrontend is configured to serve \"/my/path\" then the\n * default application should not contain any matcher that matches \"/my/path\".\n *\n * See [documentation](https://vercel.com/docs/microfrontends/troubleshooting#validatemiddlewareconfig) for more information.\n *\n * @example\n * ```ts\n * test('matches microfrontends paths', () => {\n * expect(() =>\n * validateMiddlewareConfig(config, './microfrontends.json'),\n * ).not.toThrow();\n * });\n * ```\n */\nexport function validateMiddlewareConfig(\n middlewareConfig: MiddlewareConfig,\n microfrontendConfigOrPath: string | MicrofrontendConfigIsomorphic,\n extraProductionMatches?: string[],\n): void {\n const microfrontendConfig =\n typeof microfrontendConfigOrPath === 'string'\n ? loadMicrofrontendConfigForEdge(microfrontendConfigOrPath)\n : microfrontendConfigOrPath;\n\n const errors: string[] = [];\n const usedExtraProductionMatches = new Set<string>();\n\n const wellKnownEndpoint = '/.well-known/vercel/microfrontends/client-config';\n if (!urlMatches(middlewareConfig, wellKnownEndpoint)) {\n errors.push(\n `Middleware must be configured to match ${wellKnownEndpoint}. This path is used by the client to know which flagged paths are routed to which microfrontend based on the flag values for the session. See https://nextjs.org/docs/app/building-your-application/routing/middleware#matcher for more information.`,\n );\n }\n\n for (const application of microfrontendConfig.getChildApplications()) {\n const matches = [...application.routing];\n matches.push({\n paths: [`/${application.getAssetPrefix()}/_next/:path+`],\n });\n\n for (const aMatch of matches) {\n const isFlagged = Boolean(aMatch.flag);\n\n for (const path of aMatch.paths) {\n const pathsToTest = expandWildcards(path);\n for (const testPath of pathsToTest) {\n const pathForDisplay = `${testPath}${path === testPath ? '' : ` (synthesized from ${path})`}`;\n\n const productionUrlMatches = urlMatches(middlewareConfig, testPath);\n if (isFlagged) {\n if (!urlMatches(middlewareConfig, testPath, true)) {\n errors.push(\n `Middleware should be configured to match ${pathForDisplay}. Middleware config matchers for flagged paths should ALWAYS match.`,\n );\n // Skip the remaining expanded wildcard paths (if there are any)\n // to only report a single error per wildcard.\n break;\n }\n } else if (productionUrlMatches) {\n if (extraProductionMatches?.includes(path)) {\n usedExtraProductionMatches.add(path);\n } else {\n errors.push(\n `Middleware should not match ${pathForDisplay}. This path is routed to a microfrontend and will never reach the middleware for the default application.`,\n );\n }\n // Skip the remaining expanded wildcard paths (if there are any)\n // to only report a single error per wildcard.\n break;\n }\n }\n }\n }\n }\n\n const unusedExtraProductionMatches = extraProductionMatches?.filter(\n (x) => !usedExtraProductionMatches.has(x),\n );\n if (unusedExtraProductionMatches?.length) {\n errors.push(\n `The following paths were passed to the extraProductionMatches parameter but were unused. You probably want to remove them from the extraProductionMatches parameter: ${unusedExtraProductionMatches.join(', ')}`,\n );\n }\n\n if (errors.length > 0) {\n const message = `Found the following inconsistencies between your microfrontend config ${\n typeof microfrontendConfigOrPath === 'string'\n ? `(at ${microfrontendConfigOrPath}) `\n : ''\n }and middleware config:\\n\\n- `;\n throw new Error(message + errors.join('\\n\\n- '));\n }\n}\n\n/**\n * Ensures that middleware rewrites to the correct path for flagged paths.\n * IMPORTANT: you must enable the necessary flags before calling this function.\n *\n * See [documentation](https://vercel.com/docs/microfrontends/troubleshooting#validatemiddlewareonflaggedpaths) for more information.\n *\n * @example\n * ```ts\n * jest.mock('flags/next', () => ({\n * flag: jest.fn().mockReturnValue(jest.fn().mockResolvedValue(true)),\n * }));\n *\n * test('matches microfrontends paths', () => {\n * await expect(\n * validateMiddlewareOnFlaggedPaths('./microfrontends.json', middleware),\n * ).resolves.not.toThrow();\n * });\n * ```\n */\nexport async function validateMiddlewareOnFlaggedPaths(\n microfrontendConfigOrPath: string | MicrofrontendConfigIsomorphic,\n middleware: (\n request: NextRequest,\n event: NextFetchEvent,\n ) => Promise<Response | undefined>,\n): Promise<void> {\n const initialEnv = process.env.VERCEL_ENV;\n const initialMfePreviewDomains = process.env.MFE_PREVIEW_DOMAINS;\n try {\n const microfrontendConfig =\n typeof microfrontendConfigOrPath === 'string'\n ? loadMicrofrontendConfigForEdge(microfrontendConfigOrPath)\n : microfrontendConfigOrPath;\n const allAppNames = getAllChildApplicationNames(microfrontendConfig);\n\n const errors: string[] = [];\n for (const appName of allAppNames) {\n const flaggedPaths = getFlaggedPathsForApp(microfrontendConfig, appName);\n if (flaggedPaths.length) {\n for (const path of flaggedPaths) {\n const host =\n microfrontendConfig.defaultApplication.fallback.toString();\n const requestPath = `${host}${path}`;\n const request = new NextRequest(requestPath);\n\n // eslint-disable-next-line no-await-in-loop\n const response = await middleware(\n request,\n {} as unknown as NextFetchEvent,\n );\n const routedZone = response?.headers.get(\n 'x-middleware-request-x-vercel-mfe-zone',\n );\n if (!response) {\n errors.push(\n `middleware did not action for ${requestPath}. Expected to route to ${appName}`,\n );\n } else if (response.status !== 200) {\n errors.push(\n `expected 200 status for ${requestPath} but got ${response.status}`,\n );\n } else if (routedZone !== appName) {\n errors.push(\n `expected ${requestPath} to route to ${appName}, but got ${routedZone}`,\n );\n }\n }\n }\n }\n if (errors.length) {\n throw new Error(errors.join('\\n'));\n }\n } finally {\n process.env.VERCEL_ENV = initialEnv;\n process.env.MFE_PREVIEW_DOMAINS = initialMfePreviewDomains;\n }\n}\n\n/**\n * Validates that the given paths route to the correct microfrontend.\n * The `routesToTest` parameter is a record mapping the application name\n * to a list a paths (with an optional flag) that should be routed to that\n * application. If an issue is found, this will throw an exception so that\n * it can be used with any test framework.\n *\n * See [documentation](https://vercel.com/docs/microfrontends/troubleshooting#validaterouting) for more information.\n *\n * For example:\n *\n * ```ts\n * {\n * 'microfrontend-a': ['/a/path', '/a/longer/path'],\n * 'microfrontend-b': ['/b/path'],\n * 'microfrontend-c': [\n * '/c/path',\n * {\n * 'path': '/c/flagged',\n * 'flag': 'my-flag',\n * }\n * ],\n * }\n * ```\n *\n * This ensures:\n * - `/a/path` and `/a/longer/path` get routed to `microfrontend-a`\n * - `/b/path` gets routed to `microfrontend-b`\n * - `/c/flagged` gets routed to `microfrontend-c` if `my-flag` is enabled.\n */\nexport function validateRouting(\n microfrontendConfigOrPath: string | MicrofrontendConfigIsomorphic,\n routesToTest: Record<string, (string | { path: string; flag: string })[]>,\n) {\n const microfrontendConfig =\n typeof microfrontendConfigOrPath === 'string'\n ? loadMicrofrontendConfigForEdge(microfrontendConfigOrPath)\n : microfrontendConfigOrPath;\n const matches = new Map<{ path: string; flag?: string }, string>();\n for (const application of microfrontendConfig.getChildApplications()) {\n for (const route of application.routing) {\n for (const path of route.paths) {\n matches.set({ path, flag: route.flag }, application.name);\n }\n }\n }\n const errors = [];\n for (const [applicationName, paths] of Object.entries(routesToTest)) {\n if (!microfrontendConfig.hasApplication(applicationName)) {\n errors.push(\n `Application ${applicationName} does not exist in the microfrontends config. The applications in the config are: ${microfrontendConfig\n .getAllApplications()\n .map((app) => app.name)\n .join(', ')}`,\n );\n continue;\n }\n for (const expected of paths) {\n const path = typeof expected === 'string' ? expected : expected.path;\n const flag = typeof expected === 'string' ? undefined : expected.flag;\n const matchedApplications = new Map<string, string[]>();\n const matchesWithoutFlags = new Map<string, string>();\n\n for (const [matcher, applicationMatched] of matches.entries()) {\n if (pathToRegexp(matcher.path).test(path)) {\n if (!matcher.flag || matcher.flag === flag) {\n const existingMatches =\n matchedApplications.get(applicationMatched) ?? [];\n existingMatches.push(matcher.path);\n matchedApplications.set(applicationMatched, existingMatches);\n } else {\n // This path would've matched this application if this flag was set.\n matchesWithoutFlags.set(applicationName, matcher.flag);\n }\n }\n }\n if (matchedApplications.size === 0) {\n matchedApplications.set(\n microfrontendConfig.getDefaultApplication().name,\n ['fallback to default application'],\n );\n }\n if (matchedApplications.size > 1) {\n const formattedMatches = Array.from(\n matchedApplications\n .entries()\n .map(\n ([matchedApplication, matchers]) =>\n `${matchedApplication} (on ${matchers.join(', ')})`,\n ),\n ).join(', ');\n errors.push(\n `${path} can only match one application, but it matched multiple: ${formattedMatches}`,\n );\n } else if (!matchedApplications.has(applicationName)) {\n const actualMatch = matchedApplications.entries().next().value;\n if (!actualMatch) {\n throw new Error(\"this shouldn't happen\");\n }\n const [matchedApplication, matchers] = actualMatch;\n let extraMessage = '';\n if (matchesWithoutFlags.has(applicationName)) {\n const flagToSet = matchesWithoutFlags.get(applicationName);\n extraMessage = ` It would've matched ${applicationName} if the ${flagToSet} flag was set. If this is what you want, replace ${path} in the paths-to-test list with {path: '${path}', flag: '${flagToSet}'}.`;\n }\n errors.push(\n `Expected ${path}${flag ? ` (with flag ${flag})` : ''} to match ${applicationName}, but it matched ${matchedApplication} (on ${matchers.join(', ')}).${extraMessage}`,\n );\n }\n }\n }\n if (errors.length) {\n throw new Error(\n `Incorrect microfrontends routing detected:\\n\\n- ${errors.join('\\n- ')}`,\n );\n }\n}\n","import { parse } from 'jsonc-parser';\nimport { getConfigStringFromEnv } from '../utils/get-config-from-env';\nimport { isDefaultApp } from '../../schema/utils/is-default-app';\nimport type { Config } from '../../schema/types';\nimport type { ClientConfig } from '../client/types';\nimport { MicrofrontendError } from '../../errors';\nimport { MicrofrontendConfigClient } from '../client';\nimport { type OverridesConfig, parseOverrides } from '../../overrides';\nimport { DefaultApplication, ChildApplication } from './application';\nimport { DEFAULT_LOCAL_PROXY_PORT } from './constants';\nimport {\n validateConfigDefaultApplication,\n validateConfigPaths,\n} from './validation';\n\n/**\n * A class to manage the microfrontends configuration.\n */\nexport class MicrofrontendConfigIsomorphic {\n config: Config;\n defaultApplication: DefaultApplication;\n childApplications: Record<string, ChildApplication> = {};\n overrides?: OverridesConfig;\n options?: Config['options'];\n\n private readonly serialized: {\n config: Config;\n overrides?: OverridesConfig;\n };\n\n constructor({\n config,\n overrides,\n }: {\n config: Config;\n overrides?: OverridesConfig;\n }) {\n // run validation on init\n MicrofrontendConfigIsomorphic.validate(config);\n\n const disableOverrides = config.options?.disableOverrides ?? false;\n this.overrides = overrides && !disableOverrides ? overrides : undefined;\n\n let defaultApplication: DefaultApplication | undefined;\n // create applications\n for (const [appId, appConfig] of Object.entries(config.applications)) {\n const appOverrides = !disableOverrides\n ? this.overrides?.applications[appId]\n : undefined;\n\n if (isDefaultApp(appConfig)) {\n defaultApplication = new DefaultApplication(appId, {\n app: appConfig,\n overrides: appOverrides,\n });\n } else {\n this.childApplications[appId] = new ChildApplication(appId, {\n app: appConfig,\n overrides: appOverrides,\n });\n }\n }\n\n // validate that this.defaultApplication is defined\n if (!defaultApplication) {\n throw new MicrofrontendError(\n 'Could not find default application in microfrontends configuration',\n {\n type: 'application',\n subtype: 'not_found',\n },\n );\n }\n this.defaultApplication = defaultApplication;\n\n this.config = config;\n this.options = config.options;\n this.serialized = {\n config,\n overrides,\n };\n }\n\n static validate(config: string | Config): Config {\n // let this throw if it's not valid JSON\n const c = typeof config === 'string' ? (parse(config) as Config) : config;\n\n validateConfigPaths(c.applications);\n validateConfigDefaultApplication(c.applications);\n\n return c;\n }\n\n static fromEnv({\n cookies,\n }: {\n cookies?: { name: string; value: string }[];\n }): MicrofrontendConfigIsomorphic {\n return new MicrofrontendConfigIsomorphic({\n config: parse(getConfigStringFromEnv()) as Config,\n overrides: parseOverrides(cookies ?? []),\n });\n }\n\n isOverridesDisabled(): boolean {\n return this.options?.disableOverrides ?? false;\n }\n\n getConfig(): Config {\n return this.config;\n }\n\n getApplicationsByType(): {\n defaultApplication?: DefaultApplication;\n applications: ChildApplication[];\n } {\n return {\n defaultApplication: this.defaultApplication,\n applications: Object.values(this.childApplications),\n };\n }\n\n getChildApplications(): ChildApplication[] {\n return Object.values(this.childApplications);\n }\n\n getAllApplications(): (DefaultApplication | ChildApplication)[] {\n return [\n this.defaultApplication,\n ...Object.values(this.childApplications),\n ].filter(Boolean);\n }\n\n getApplication(name: string): DefaultApplication | ChildApplication {\n // check the default\n if (\n this.defaultApplication.name === name ||\n this.defaultApplication.packageName === name\n ) {\n return this.defaultApplication;\n }\n const app =\n this.childApplications[name] ||\n Object.values(this.childApplications).find(\n (child) => child.packageName === name,\n );\n if (!app) {\n throw new MicrofrontendError(\n `Could not find microfrontends configuration for application \"${name}\"`,\n {\n type: 'application',\n subtype: 'not_found',\n },\n );\n }\n\n return app;\n }\n\n hasApplication(name: string): boolean {\n try {\n this.getApplication(name);\n return true;\n } catch {\n return false;\n }\n }\n\n getApplicationByProjectName(\n projectName: string,\n ): DefaultApplication | ChildApplication | undefined {\n // check the default\n if (this.defaultApplication.name === projectName) {\n return this.defaultApplication;\n }\n\n return Object.values(this.childApplications).find(\n (app) => app.name === projectName,\n );\n }\n\n /**\n * Returns the default application.\n */\n getDefaultApplication(): DefaultApplication {\n return this.defaultApplication;\n }\n\n /**\n * Returns the configured port for the local proxy\n */\n getLocalProxyPort(): number {\n return this.config.options?.localProxyPort ?? DEFAULT_LOCAL_PROXY_PORT;\n }\n\n /**\n * Serializes the class back to the Schema type.\n *\n * NOTE: This is used when writing the config to disk and must always match the input Schema\n */\n toSchemaJson(): Config {\n return this.serialized.config;\n }\n\n toClientConfig(): MicrofrontendConfigClient {\n const applications: ClientConfig['applications'] = Object.fromEntries(\n Object.entries(this.childApplications).map(([name, application]) => [\n name,\n {\n default: false,\n routing: application.routing,\n },\n ]),\n );\n\n // add the default application\n applications[this.defaultApplication.name] = {\n default: true,\n };\n\n return new MicrofrontendConfigClient({\n applications,\n });\n }\n\n serialize(): {\n config: Config;\n overrides?: OverridesConfig;\n } {\n return this.serialized;\n }\n}\n","export type MicrofrontendErrorType =\n | 'config'\n | 'packageJson'\n | 'vercelJson'\n | 'application'\n | 'unknown';\n\nexport type MicrofrontendErrorSubtype =\n | 'not_found'\n | 'inference_failed'\n | 'not_found_in_env'\n | 'invalid_asset_prefix'\n | 'invalid_main_path'\n | 'does_not_match_schema'\n | 'unable_to_read_file'\n | 'unsupported_validation_env'\n | 'unsupported_version'\n | 'invalid_path'\n | 'invalid_permissions'\n | 'invalid_syntax'\n | 'missing_microfrontend_config_path'\n | 'unsupported_operation';\n\n// A mapping of error types to their subtypes.\ninterface TypeToSubtype {\n application:\n | 'invalid_asset_prefix'\n | 'invalid_path'\n | 'multiple_package_managers'\n | 'not_found';\n config:\n | 'conflicting_paths'\n | 'depcrecated_field'\n | 'does_not_match_schema'\n | 'invalid_main_path'\n | 'invalid_preview_deployment_suffix'\n | 'multiple_default_applications'\n | 'no_default_application'\n | 'not_found_in_env'\n | 'not_found'\n | 'inference_failed'\n | 'unable_to_read_file'\n | 'invalid_syntax'\n | 'invalid_permissions'\n | 'unsupported_operation'\n | 'unsupported_validation_env'\n | 'unsupported_version';\n packageJson:\n | 'missing_field_name'\n | 'unable_to_read_file'\n | 'invalid_permissions'\n | 'invalid_syntax';\n vercelJson:\n | 'missing_field_microfrontend_config_path'\n | 'unable_to_read_file'\n | 'invalid_permissions'\n | 'invalid_syntax';\n unknown: never;\n}\n\nexport type MicrofrontendErrorSource =\n | '@vercel/microfrontends'\n | '@vercel/microfrontends/next'\n | 'fs'\n | 'ajv';\n\nexport interface MicrofrontendErrorOptions<T extends MicrofrontendErrorType> {\n cause?: unknown;\n source?: MicrofrontendErrorSource;\n type?: T;\n subtype?: TypeToSubtype[T];\n}\n\ninterface HandleOptions {\n fileName?: string;\n}\n\nexport class MicrofrontendError<\n T extends MicrofrontendErrorType = 'unknown',\n> extends Error {\n public source: MicrofrontendErrorSource;\n public type: T;\n public subtype?: TypeToSubtype[T];\n\n constructor(message: string, opts?: MicrofrontendErrorOptions<T>) {\n super(message, { cause: opts?.cause });\n this.name = 'MicrofrontendsError';\n this.source = opts?.source ?? '@vercel/microfrontends';\n this.type = opts?.type ?? ('unknown' as T);\n this.subtype = opts?.subtype;\n Error.captureStackTrace(this, MicrofrontendError);\n }\n\n isKnown(): boolean {\n return this.type !== 'unknown';\n }\n\n isUnknown(): boolean {\n return !this.isKnown();\n }\n\n /**\n * Converts an error to a MicrofrontendsError.\n * @param original - The original error to convert.\n * @returns The converted MicrofrontendsError.\n */\n static convert(\n original: Error,\n opts?: HandleOptions,\n ): MicrofrontendError<MicrofrontendErrorType> {\n if (opts?.fileName) {\n const err = MicrofrontendError.convertFSError(original, opts.fileName);\n if (err) {\n return err;\n }\n }\n\n if (\n original.message.includes(\n 'Code generation from strings disallowed for this context',\n )\n ) {\n return new MicrofrontendError(original.message, {\n type: 'config',\n subtype: 'unsupported_validation_env',\n source: 'ajv',\n });\n }\n\n // unknown catch-all\n return new MicrofrontendError(original.message);\n }\n\n static convertFSError(\n original: Error,\n fileName: string,\n ): MicrofrontendError<MicrofrontendErrorType> | null {\n if (original instanceof Error && 'code' in original) {\n if (original.code === 'ENOENT') {\n return new MicrofrontendError(`Could not find \"${fileName}\"`, {\n type: 'config',\n subtype: 'unable_to_read_file',\n source: 'fs',\n });\n }\n if (original.code === 'EACCES') {\n return new MicrofrontendError(\n `Permission denied while accessing \"${fileName}\"`,\n {\n type: 'config',\n subtype: 'invalid_permissions',\n source: 'fs',\n },\n );\n }\n }\n\n if (original instanceof SyntaxError) {\n return new MicrofrontendError(\n `Failed to parse \"${fileName}\": Invalid JSON format.`,\n {\n type: 'config',\n subtype: 'invalid_syntax',\n source: 'fs',\n },\n );\n }\n\n return null;\n }\n\n /**\n * Handles an unknown error and returns a MicrofrontendsError instance.\n * @param err - The error to handle.\n * @returns A MicrofrontendsError instance.\n */\n static handle(\n err: unknown,\n opts?: HandleOptions,\n ): MicrofrontendError<MicrofrontendErrorType> {\n if (err instanceof MicrofrontendError) {\n return err as MicrofrontendError<MicrofrontendErrorType>;\n }\n\n // handle Error instances\n if (err instanceof Error) {\n return MicrofrontendError.convert(err, opts);\n }\n\n // handle object errors\n if (typeof err === 'object' && err !== null) {\n if ('message' in err && typeof err.message === 'string') {\n return MicrofrontendError.convert(new Error(err.message), opts);\n }\n }\n\n return new MicrofrontendError('An unknown error occurred');\n }\n}\n","import { MicrofrontendError } from '../../errors';\n\n/**\n * Utility to fetch the microfrontend configuration string from the environment.\n */\nexport function getConfigStringFromEnv(): string {\n const config = process.env.MFE_CONFIG;\n if (!config) {\n throw new MicrofrontendError(`Missing \"MFE_CONFIG\" in environment.`, {\n type: 'config',\n subtype: 'not_found_in_env',\n });\n }\n return config;\n}\n","import type { Application, DefaultApplication } from '../types';\n\nexport function isDefaultApp(a: Application): a is DefaultApplication {\n return !('routing' in a);\n}\n","import { pathToRegexp } from 'path-to-regexp';\nimport type { ClientConfig } from './types';\n\nexport interface MicrofrontendConfigClientOptions {\n removeFlaggedPaths?: boolean;\n}\n\nconst regexpCache = new Map<string, RegExp>();\nconst getRegexp = (path: string): RegExp => {\n const existing = regexpCache.get(path);\n if (existing) {\n return existing;\n }\n\n const regexp = pathToRegexp(path);\n regexpCache.set(path, regexp);\n return regexp;\n};\n\nexport class MicrofrontendConfigClient {\n applications: ClientConfig['applications'];\n pathCache: Record<string, string> = {};\n private readonly serialized: ClientConfig;\n\n constructor(config: ClientConfig, opts?: MicrofrontendConfigClientOptions) {\n this.serialized = config;\n if (opts?.removeFlaggedPaths) {\n for (const app of Object.values(config.applications)) {\n if (app.routing) {\n app.routing = app.routing.filter((match) => !match.flag);\n }\n }\n }\n this.applications = config.applications;\n }\n\n /**\n * Create a new `MicrofrontendConfigClient` from a JSON string.\n * Config must be passed in to remain framework agnostic\n */\n static fromEnv(\n config: string | undefined,\n opts?: MicrofrontendConfigClientOptions,\n ): MicrofrontendConfigClient {\n if (!config) {\n throw new Error(\n 'Could not construct MicrofrontendConfigClient: configuration is empty or undefined. Did you set up your application with `withMicrofrontends`?',\n );\n }\n return new MicrofrontendConfigClient(\n JSON.parse(config) as ClientConfig,\n opts,\n );\n }\n\n isEqual(other: MicrofrontendConfigClient): boolean {\n return (\n this === other ||\n JSON.stringify(this.applications) === JSON.stringify(other.applications)\n );\n }\n\n getApplicationNameForPath(path: string): string | null {\n if (!path.startsWith('/')) {\n throw new Error(`Path must start with a /`);\n }\n\n if (this.pathCache[path]) {\n return this.pathCache[path];\n }\n\n const pathname = new URL(path, 'https://example.com').pathname;\n for (const [name, application] of Object.entries(this.applications)) {\n if (application.routing) {\n for (const group of application.routing) {\n for (const childPath of group.paths) {\n const regexp = getRegexp(childPath);\n if (regexp.test(pathname)) {\n this.pathCache[path] = name;\n return name;\n }\n }\n }\n }\n }\n const defaultApplication = Object.entries(this.applications).find(\n ([, application]) => application.default,\n );\n if (!defaultApplication) {\n return null;\n }\n\n this.pathCache[path] = defaultApplication[0];\n return defaultApplication[0];\n }\n\n serialize(): ClientConfig {\n return this.serialized;\n }\n}\n","// cookie name needs to match proxy\n// https://github.com/vercel/proxy/blob/fb00d723136ad539a194e4a851dd272010527c35/lib/routing/micro_frontends_overrides.lua#L7\nexport const OVERRIDES_COOKIE_PREFIX = 'vercel-micro-frontends-override';\nexport const OVERRIDES_ENV_COOKIE_PREFIX = `${OVERRIDES_COOKIE_PREFIX}:env:`;\n","import { OVERRIDES_COOKIE_PREFIX } from './constants';\n\nexport function isOverrideCookie(cookie: { name?: string }): boolean {\n return Boolean(cookie.name?.startsWith(OVERRIDES_COOKIE_PREFIX));\n}\n","import { isOverrideCookie } from './is-override-cookie';\nimport { OVERRIDES_ENV_COOKIE_PREFIX } from './constants';\n\nexport function getOverrideFromCookie(cookie: {\n name: string;\n value?: string | null;\n}): { application: string; host: string } | undefined {\n if (!isOverrideCookie(cookie) || !cookie.value) return;\n return {\n application: cookie.name.replace(OVERRIDES_ENV_COOKIE_PREFIX, ''),\n host: cookie.value,\n };\n}\n","import type { OverridesConfig } from './types';\nimport { getOverrideFromCookie } from './get-override-from-cookie';\n\nexport function parseOverrides(\n cookies: { name: string; value?: string | null }[],\n): OverridesConfig {\n const overridesConfig: OverridesConfig = { applications: {} };\n\n cookies.forEach((cookie) => {\n const override = getOverrideFromCookie(cookie);\n if (!override) return;\n overridesConfig.applications[override.application] = {\n environment: { host: override.host },\n };\n });\n\n return overridesConfig;\n}\n","import { pathToRegexp, parse as parsePathRegexp } from 'path-to-regexp';\nimport type {\n ApplicationId,\n PathGroup,\n ApplicationRouting,\n ChildApplication as ChildApplicationConfig,\n} from '../../schema/types';\nimport { MicrofrontendError } from '../../errors';\nimport { isDefaultApp } from '../../schema/utils/is-default-app';\n\nconst LIST_FORMATTER = new Intl.ListFormat('en', {\n style: 'long',\n type: 'conjunction',\n});\n\n/**\n * Validate all paths in a configuration - ensures paths do not overlap\n */\nexport const validateConfigPaths = (\n applicationConfigsById?: ApplicationRouting,\n): void => {\n if (!applicationConfigsById) {\n return;\n }\n\n const pathsByApplicationId = new Map<\n PathGroup['paths'][number],\n {\n applications: ApplicationId[];\n matcher: RegExp;\n applicationId?: ApplicationId;\n }\n >();\n const errors: string[] = [];\n\n for (const [id, app] of Object.entries(applicationConfigsById)) {\n if (isDefaultApp(app)) {\n // default applications do not have routing\n continue;\n }\n\n for (const pathMatch of app.routing) {\n for (const path of pathMatch.paths) {\n const maybeError = validatePathExpression(path);\n if (maybeError) {\n errors.push(maybeError);\n } else {\n const existing = pathsByApplicationId.get(path);\n if (existing) {\n existing.applications.push(id);\n } else {\n pathsByApplicationId.set(path, {\n applications: [id],\n matcher: pathToRegexp(path),\n applicationId: id,\n });\n }\n }\n }\n }\n }\n const entries = Array.from(pathsByApplicationId.entries());\n\n for (const [path, { applications: ids, matcher, applicationId }] of entries) {\n if (ids.length > 1) {\n errors.push(\n `Duplicate path \"${path}\" for applications \"${ids.join(', ')}\"`,\n );\n }\n\n for (const [\n matchPath,\n { applications: matchIds, applicationId: matchApplicationId },\n ] of entries) {\n if (path === matchPath) {\n // we're comparing to ourselves, so skip\n continue;\n }\n\n if (applicationId === matchApplicationId) {\n // we're comparing to paths within our own application, which are allowed to overlap, so skip\n continue;\n }\n\n if (matcher.test(matchPath)) {\n const source = `\"${path}\" of application${ids.length > 0 ? 's' : ''} ${ids.join(', ')}`;\n const destination = `\"${matchPath}\" of application${matchIds.length > 0 ? 's' : ''} ${matchIds.join(', ')}`;\n\n errors.push(\n `Overlapping path detected between ${source} and ${destination}`,\n );\n }\n }\n }\n\n if (errors.length) {\n throw new MicrofrontendError(\n `Invalid paths: ${errors.join(', ')}. See supported paths in the documentation https://vercel.com/docs/microfrontends/path-routing#supported-path-expressions.`,\n {\n type: 'config',\n subtype: 'conflicting_paths',\n },\n );\n }\n};\n\n// From https://github.com/pillarjs/path-to-regexp/blob/b0778f5e8e6c6e9ee4e2f5b34e877cc5229f8036/src/index.ts#L143\nconst PATH_DEFAULT_PATTERN = '[^\\\\/#\\\\?]+?';\n\nfunction validatePathExpression(path: string): string | undefined {\n try {\n const tokens = parsePathRegexp(path);\n if (/(?<!\\\\)\\{/.test(path)) {\n return `Optional paths are not supported: ${path}`;\n }\n if (/(?<!\\\\|\$)\\?/.test(path)) {\n return `Optional paths are not supported: ${path}`;\n }\n if (/\\/[^/]*(?<!\\\$:[^/]*(?<!\\\\):[^/]*/.test(path)) {\n return `Only one wildcard is allowed per path segment: ${path}`;\n }\n for (let i = 0; i < tokens.length; i++) {\n const token = tokens[i];\n if (token === undefined) {\n return `token ${i} in ${path} is undefined, this shouldn't happen`;\n }\n if (typeof token !== 'string') {\n if (!token.name) {\n return `Only named wildcards are allowed: ${path} (hint: add \":path\" to the wildcard)`;\n }\n if (\n token.pattern !== PATH_DEFAULT_PATTERN &&\n // Allows (a|b|c) and ((?!a|b|c).*) regex\n // Only limited regex is supported for now, due to performance considerations\n !/^(?<allowed>[\\w]+(?:\\|[^:|()]+)+)$|^\$\\?!(?<disallowed>[\\w]+(?:\\|[^:|()]+)*)\$\\.\\*$/.test(\n token.pattern,\n )\n ) {\n return `Path ${path} cannot use unsupported regular expression wildcard`;\n }\n if (token.modifier && i !== tokens.length - 1) {\n return `Modifier ${token.modifier} is not allowed on wildcard :${token.name} in ${path}. Modifiers are only allowed in the last path component`;\n }\n }\n }\n } catch (e) {\n const message = e instanceof Error ? e.message : String(e);\n return `Path ${path} could not be parsed into regexp: ${message}`;\n }\n return undefined;\n}\n\n/**\n * Validate all paths in an application - ensures paths are the correct format\n */\nexport const validateAppPaths = (\n name: string,\n app: ChildApplicationConfig,\n): void => {\n // validate routes\n for (const group of app.routing) {\n for (const p of group.paths) {\n if (p === '/') {\n continue;\n }\n if (p.endsWith('/')) {\n throw new MicrofrontendError(\n `Invalid path for application \"${name}\". ${p} must not end with a slash.`,\n { type: 'application', subtype: 'invalid_path' },\n );\n }\n\n if (!p.startsWith('/')) {\n throw new MicrofrontendError(\n `Invalid path for application \"${name}\". ${p} must start with a slash.`,\n { type: 'application', subtype: 'invalid_path' },\n );\n }\n }\n }\n};\n\n/**\n * Make sure only one `Application` defines routing\n * */\nexport const validateConfigDefaultApplication = (\n applicationConfigsById?: ApplicationRouting,\n): void => {\n if (!applicationConfigsById) {\n return;\n }\n\n const applicationsWithoutRouting = Object.entries(\n applicationConfigsById,\n ).filter(([, app]) => isDefaultApp(app));\n const numApplicationsWithoutRouting = applicationsWithoutRouting.reduce(\n (acc) => {\n return acc + 1;\n },\n 0,\n );\n\n if (numApplicationsWithoutRouting === 0) {\n throw new MicrofrontendError(\n 'No default application found. At least one application needs to be the default by omitting routing.',\n { type: 'config', subtype: 'no_default_application' },\n );\n }\n\n if (numApplicationsWithoutRouting > 1) {\n const applicationNamesMissingRouting = applicationsWithoutRouting.map(\n ([name]) => name,\n );\n throw new MicrofrontendError(\n `All applications except for the default app must contain the \"routing\" field. Applications that are missing routing: ${LIST_FORMATTER.format(applicationNamesMissingRouting)}.`,\n { type: 'config', subtype: 'multiple_default_applications' },\n );\n }\n};\n","const PREFIX = 'vc-ap';\n\nexport function generateAssetPrefixFromName({\n name,\n}: {\n name: string;\n}): string {\n if (!name) {\n throw new Error('Name is required to generate an asset prefix');\n }\n\n return `${PREFIX}-${name}`;\n}\n","export function generatePortFromName({\n name,\n minPort = 3000,\n maxPort = 8000,\n}: {\n name: string;\n minPort?: number;\n maxPort?: number;\n}): number {\n if (!name) {\n throw new Error('Name is required to generate a port');\n }\n\n // hash the name\n let hash = 0;\n for (let i = 0; i < name.length; i++) {\n // eslint-disable-next-line no-bitwise\n hash = (hash << 5) - hash + name.charCodeAt(i);\n // Convert to 32-bit\n // eslint-disable-next-line no-bitwise\n hash |= 0;\n }\n hash = Math.abs(hash);\n\n // Map the hash to the port range\n const range = maxPort - minPort;\n const port = minPort + (hash % range);\n\n return port;\n}\n","import type {\n HostConfig as RemoteHostConfigSchema,\n LocalHostConfig as LocalHostConfigSchema,\n} from '../../../bin/types';\nimport { generatePortFromName } from './utils/generate-port';\n\ninterface HostOptions {\n isLocal?: boolean;\n}\n\nexport class Host {\n protocol: 'http' | 'https';\n host: string;\n port?: number;\n local: boolean | undefined;\n\n constructor(\n hostConfig: RemoteHostConfigSchema | string,\n options?: HostOptions,\n ) {\n if (typeof hostConfig === 'string') {\n ({\n protocol: this.protocol,\n host: this.host,\n port: this.port,\n } = Host.parseUrl(hostConfig));\n } else {\n const { protocol = 'https', host, port } = hostConfig;\n this.protocol = protocol;\n this.host = host;\n this.port = port;\n }\n this.local = options?.isLocal;\n }\n\n protected static parseUrl(\n url: string,\n defaultProtocol = 'https',\n ): {\n protocol: Host['protocol'];\n host: string;\n port?: number;\n } {\n let hostToParse = url;\n if (!/^https?:\\/\\//.exec(hostToParse)) {\n hostToParse = `${defaultProtocol}://${hostToParse}`;\n }\n const parsed = new URL(hostToParse);\n if (!parsed.hostname) {\n throw new Error(Host.getMicrofrontendsError(url, 'requires a host'));\n }\n if (parsed.hash) {\n throw new Error(\n Host.getMicrofrontendsError(url, 'cannot have a fragment'),\n );\n }\n if (parsed.username || parsed.password) {\n throw new Error(\n Host.getMicrofrontendsError(\n url,\n 'cannot have authentication credentials (username and/or password)',\n ),\n );\n }\n if (parsed.pathname !== '/') {\n throw new Error(Host.getMicrofrontendsError(url, 'cannot have a path'));\n }\n if (parsed.search) {\n throw new Error(\n Host.getMicrofrontendsError(url, 'cannot have query parameters'),\n );\n }\n const protocol = parsed.protocol.slice(0, -1) as Host['protocol'];\n return {\n protocol,\n host: parsed.hostname,\n port: parsed.port ? Number.parseInt(parsed.port) : undefined,\n };\n }\n\n private static getMicrofrontendsError(url: string, message: string): string {\n return `Microfrontends configuration error: the URL ${url} in your microfrontends.json ${message}.`;\n }\n\n isLocal(): boolean {\n return this.local || this.host === 'localhost' || this.host === '127.0.0.1';\n }\n\n toString(): string {\n const url = this.toUrl();\n // strip the trailing slash\n return url.toString().replace(/\\/$/, '');\n }\n\n toUrl(): URL {\n const url = `${this.protocol}://${this.host}${this.port ? `:${this.port}` : ''}`;\n return new URL(url);\n }\n}\n\n/**\n * A Host subclass with defaults for locally running applications\n */\nexport class LocalHost extends Host {\n constructor({\n appName,\n local,\n }: {\n appName: string;\n local?: string | number | LocalHostConfigSchema;\n }) {\n let protocol: RemoteHostConfigSchema['protocol'];\n let host: string | undefined;\n let port: number | undefined;\n if (typeof local === 'number') {\n port = local;\n } else if (typeof local === 'string') {\n if (/^\\d+$/.test(local)) {\n port = Number.parseInt(local);\n } else {\n const parsed = Host.parseUrl(local, 'http');\n protocol = parsed.protocol;\n host = parsed.host;\n port = parsed.port;\n }\n } else if (local) {\n protocol = local.protocol;\n host = local.host;\n port = local.port;\n }\n // set defaults for local\n super({\n protocol: protocol ?? 'http',\n host: host ?? 'localhost',\n port: port ?? generatePortFromName({ name: appName }),\n });\n }\n}\n","export function generateAutomationBypassEnvVarName({\n name,\n}: {\n name: string;\n}): string {\n return `AUTOMATION_BYPASS_${name.toUpperCase().replace(/[^a-zA-Z0-9]/g, '_')}`;\n}\n","import type {\n Application as ApplicationConfig,\n DefaultApplication as DefaultApplicationConfig,\n ChildApplication as ChildApplicationConfig,\n PathGroup,\n} from '../../schema/types';\nimport type { ApplicationOverrideConfig } from '../../overrides';\nimport { validateAppPaths } from './validation';\nimport { generateAssetPrefixFromName } from './utils/generate-asset-prefix';\nimport { Host, LocalHost } from './host';\nimport { generateAutomationBypassEnvVarName } from './utils/generate-automation-bypass-env-var-name';\n\nexport class Application {\n readonly default: boolean;\n name: string;\n development: {\n local: LocalHost;\n fallback?: Host;\n };\n fallback?: Host;\n packageName?: string;\n overrides?: {\n environment?: Host;\n };\n readonly serialized: ApplicationConfig;\n\n constructor(\n name: string,\n {\n app,\n overrides,\n isDefault,\n }: {\n app: ApplicationConfig;\n overrides?: ApplicationOverrideConfig;\n isDefault?: boolean;\n },\n ) {\n this.name = name;\n this.development = {\n local: new LocalHost({\n appName: name,\n local: app.development?.local,\n }),\n fallback: app.development?.fallback\n ? new Host(app.development.fallback)\n : undefined,\n };\n if (app.development?.fallback) {\n this.fallback = new Host(app.development.fallback);\n }\n this.packageName = app.packageName;\n this.overrides = overrides?.environment\n ? {\n environment: new Host(overrides.environment),\n }\n : undefined;\n this.default = isDefault ?? false;\n this.serialized = app;\n }\n\n isDefault(): boolean {\n return this.default;\n }\n\n getAssetPrefix(): string {\n return generateAssetPrefixFromName({ name: this.name });\n }\n\n getAutomationBypassEnvVarName(): string {\n return generateAutomationBypassEnvVarName({ name: this.name });\n }\n\n serialize(): ApplicationConfig {\n return this.serialized;\n }\n}\n\nexport class DefaultApplication extends Application {\n readonly default = true;\n fallback: Host;\n\n constructor(\n name: string,\n {\n app,\n overrides,\n }: {\n app: DefaultApplicationConfig;\n overrides?: ApplicationOverrideConfig;\n },\n ) {\n super(name, {\n app,\n overrides,\n isDefault: true,\n });\n\n this.fallback = new Host(app.development.fallback);\n }\n\n getAssetPrefix(): string {\n return '';\n }\n}\n\nexport class ChildApplication extends Application {\n readonly default = false;\n routing: PathGroup[];\n\n constructor(\n name: string,\n {\n app,\n overrides,\n }: {\n app: ChildApplicationConfig;\n overrides?: ApplicationOverrideConfig;\n },\n ) {\n // validate\n ChildApplication.validate(name, app);\n\n super(name, {\n app,\n overrides,\n isDefault: false,\n });\n\n this.routing = app.routing;\n }\n\n static validate(name: string, app: ChildApplicationConfig): void {\n // validate routes\n validateAppPaths(name, app);\n }\n}\n","export const DEFAULT_LOCAL_PROXY_PORT = 3024;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,qBAA6B;AAC7B,oBAIO;AACP,IAAAA,yBAAoC;AACpC,IAAAC,uBAAsB;;;ACPtB,0BAAsB;;;AC6Ef,IAAM,qBAAN,cAEG,MAAM;AAAA,EAKd,YAAY,SAAiB,MAAqC;AAChE,UAAM,SAAS,EAAE,OAAO,MAAM,MAAM,CAAC;AACrC,SAAK,OAAO;AACZ,SAAK,SAAS,MAAM,UAAU;AAC9B,SAAK,OAAO,MAAM,QAAS;AAC3B,SAAK,UAAU,MAAM;AACrB,UAAM,kBAAkB,MAAM,kBAAkB;AAAA,EAClD;AAAA,EAEA,UAAmB;AACjB,WAAO,KAAK,SAAS;AAAA,EACvB;AAAA,EAEA,YAAqB;AACnB,WAAO,CAAC,KAAK,QAAQ;AAAA,EACvB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,OAAO,QACL,UACA,MAC4C;AAC5C,QAAI,MAAM,UAAU;AAClB,YAAM,MAAM,mBAAmB,eAAe,UAAU,KAAK,QAAQ;AACrE,UAAI,KAAK;AACP,eAAO;AAAA,MACT;AAAA,IACF;AAEA,QACE,SAAS,QAAQ;AAAA,MACf;AAAA,IACF,GACA;AACA,aAAO,IAAI,mBAAmB,SAAS,SAAS;AAAA,QAC9C,MAAM;AAAA,QACN,SAAS;AAAA,QACT,QAAQ;AAAA,MACV,CAAC;AAAA,IACH;AAGA,WAAO,IAAI,mBAAmB,SAAS,OAAO;AAAA,EAChD;AAAA,EAEA,OAAO,eACL,UACA,UACmD;AACnD,QAAI,oBAAoB,SAAS,UAAU,UAAU;AACnD,UAAI,SAAS,SAAS,UAAU;AAC9B,eAAO,IAAI,mBAAmB,mBAAmB,aAAa;AAAA,UAC5D,MAAM;A