/microfrontends

Testing & Troubleshooting Reference

Testing Utilities

The @vercel/microfrontends package includes test utilities imported from @vercel/microfrontends/next/testing. All utilities throw exceptions on failure, so they work with any test framework.

validateMiddlewareConfig

Validates that Next.js middleware is configured correctly for microfrontends. Run only on the default application.

Checks:

• Middleware matches /.well-known/vercel/microfrontends/client-config
• Middleware does not match paths routed to child microfrontends (those requests never reach the default app's middleware)
• Middleware does match all flagged paths

// tests/middleware.test.ts
/* @jest-environment node */
import { validateMiddlewareConfig } from "@vercel/microfrontends/next/testing";
import { config } from "../middleware";

describe("middleware", () => {
  test("matches microfrontends paths", () => {
    expect(() =>
      validateMiddlewareConfig(config, "./microfrontends.json"),
    ).not.toThrow();
  });
});

Signature:

function validateMiddlewareConfig(
  middlewareConfig: MiddlewareConfig,
  microfrontendConfigOrPath: string | MicrofrontendConfigIsomorphic,
  extraProductionMatches?: string[],
): void;

• middlewareConfig: The exported config from your middleware.ts
• microfrontendConfigOrPath: Path to microfrontends.json or a parsed config object
• extraProductionMatches: Optional paths that middleware intentionally matches despite being child app paths

validateMiddlewareOnFlaggedPaths

Validates that middleware correctly rewrites flagged paths to the right microfrontend. All flags must be enabled before calling this function.

// tests/middleware.test.ts
/* @jest-environment node */
import { validateMiddlewareOnFlaggedPaths } from "@vercel/microfrontends/next/testing";
import { middleware } from "../middleware";

// Enable all flags before testing.
// This mock is specific to the Flags SDK; adapt if using a custom flag implementation.
jest.mock("flags/next", () => ({
  flag: jest.fn().mockReturnValue(jest.fn().mockResolvedValue(true)),
}));

describe("middleware", () => {
  test("rewrites for flagged paths", async () => {
    await expect(
      validateMiddlewareOnFlaggedPaths("./microfrontends.json", middleware),
    ).resolves.not.toThrow();
  });
});

Signature:

async function validateMiddlewareOnFlaggedPaths(
  microfrontendConfigOrPath: string | MicrofrontendConfigIsomorphic,
  middleware: (
    request: NextRequest,
    event: NextFetchEvent,
  ) => Promise<Response | undefined>,
): Promise<void>;

validateRouting

Validates that specific paths route to the correct microfrontend application. Run only on the default application where microfrontends.json is defined.

// tests/microfrontends.test.ts
import { validateRouting } from "@vercel/microfrontends/next/testing";

describe("microfrontends", () => {
  test("routing", () => {
    expect(() => {
      validateRouting("./microfrontends.json", {
        marketing: ["/", "/products"],
        docs: ["/docs", "/docs/api"],
        dashboard: [
          "/dashboard",
          { path: "/new-dashboard", flag: "enable-new-dashboard" },
        ],
      });
    }).not.toThrow();
  });
});

Signature:

function validateRouting(
  microfrontendConfigOrPath: string | MicrofrontendConfigIsomorphic,
  routesToTest: Record<string, (string | { path: string; flag: string })[]>,
): void;

The routesToTest maps application names to arrays of paths. Each path can be:

• A string: '/docs' — asserts this path routes to the named app
• An object: { path: '/new-docs', flag: 'my-flag' } — asserts this path routes to the named app when the flag is enabled

Debug Headers

Enable debug headers to inspect routing decisions on deployed environments.

Enabling

• Use the Vercel Toolbar → enable Routing Debug Mode, or
• Set browser cookie VERCEL_MFE_DEBUG=1

Response headers

Debug Routing Locally

Enable debug logging for the local proxy:

1. Set MFE_DEBUG=1 environment variable, or
2. Pass debug: true to withMicrofrontends:

export default withMicrofrontends(nextConfig, { debug: true });

The proxy logs show:

• Which path matched which routing rule
• Whether the request went to a local app or fallback
• Environment variable and rewrite changes

Observability & Tracing

Observability dashboard

Microfrontend routing data appears in the Observability tab under the CDN section → Microfrontends.

Session tracing

Routing is captured in Session Tracing. The Microfrontends span includes:

Common Issues

Microfrontends aren't working in local development

1. Enable debug logging (MFE_DEBUG=1) to see routing decisions
2. Verify the proxy is running and you're accessing the proxy URL (not the app's direct port)
3. Check that --local-apps includes the correct app name
4. Verify microfrontends.json is accessible (auto-detected in monorepos, needs manual config in polyrepos)

Requests not routed to the correct microfrontend in production

1. Verify the path is covered by the routing config using the Deployment Summary or Vercel Toolbar
2. Enable debug headers and inspect x-vercel-mfe-matched-path and x-vercel-mfe-app
3. Check session traces for detailed routing information

Middleware not running for flagged paths

• Ensure flagged paths are listed in the middleware matcher config
• Verify /.well-known/vercel/microfrontends/client-config is in the matcher
• Use validateMiddlewareConfig and validateMiddlewareOnFlaggedPaths tests to catch misconfigurations

Asset 404 errors

• Verify the asset prefix is correctly configured and routed in microfrontends.json
• For Next.js public/ directory files, move them to a subdirectory matching the asset prefix
• Check that withMicrofrontends (or the Vite plugin) is applied to the framework config

Deployment protection blocking fallbacks locally

• The default app's VERCEL_AUTOMATION_BYPASS_SECRET is used to bypass protection on child projects — ensure that secret is also added as a Protection Bypass for Automation secret in each protected child project
• Add VERCEL_AUTOMATION_BYPASS_SECRET=<secret> to the default app's local environment file (e.g. .env.local)