Testing & troubleshooting microfrontends

The @vercel/microfrontends package includes some test utilities to help avoid many common misconfigurations.

This test ensures Middleware is configured to work correctly with microfrontends. Passing this test does not guarantee Middleware is set up correctly, but this should find many common problems.

Since Middleware only runs in the default application, you should only run this test on the default application. If it finds a configuration issue, it will throw an exception so that you can use it with any test framework.

/* @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();
  });
});

This test checks that Middleware is correctly configured for flagged paths by ensuring that Middleware rewrites to the correct path for these flagged paths. Since Middleware only runs in the default application, you should only run this testing utility in the default application.

/* @jest-environment node */
 
import { validateMiddlewareOnFlaggedPaths } from '@vercel/microfrontends/next/testing';
import { middleware } from '../middleware';
 
// For this test to work, all flags must be enabled before calling
// validateMiddlewareOnFlaggedPaths. There are many ways to do this depending
// on your flag framework, test framework, etc. but this is one way to do it
// with https://flags-sdk.dev/
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();
  });
});

This test validates that the given paths route to the correct microfrontend. You should only add this test to the default application where the microfrontends.json file is defined.

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();
  });
});

The above test confirms that microfrontends routing:

• Routes / and /products to the marketing microfrontend.
• Routes /docs and /docs/api to the docs microfrontend.
• Routes /dashboard and /new-dashboard (with the enable-new-dashboard flag enabled) to the dashboard microfrontend.

Find a list of common issues you might face with debugging tips:

To debug issues with microfrontends locally, set MFE_DEBUG=1 as an environment variable when running your application. Details about changes to your application, such as envronment variables and rewrites, will be printed to the console. If using the local development proxy, the logs will also print the name of the application and URL of the destination where each request was routed to.

To validate where requests are being routed to in production, follow these steps:

1. Verify that the path is covered by the microfrontends routing configuration.
2. Enable microfrontends debug mode in the Vercel Toolbar. Requests to your domain will now return additional headers on every response that you can use to verify the correct application handled the request:
   • x-vercel-zone: The name of the microfrontend that handled the request.
   • x-vercel-mfe-host: The hostname of the deployment that handled the request.
   • x-vercel-mfe-zone-from-middleware: For flagged paths, the name of the microfrontend that middleware decided should handle the request.