Microfrontends path routing

Vercel handles routing to microfrontends directly in Vercel's network infrastructure, simplifying the setup and improving latency. When Vercel receives a request to a domain that uses microfrontends, we read the microfrontends.json file in the live deployment to decide where to route it.

You can also route paths to a different microfrontend based on custom application logic using middleware.

With microfrontends, the default path for an application cannot be / since the application may only serve a subset of paths. To update the default route, visit the Microfrontends Settings page.

1. Go to the Settings tab for your project
2. Click on the Microfrontends tab
3. Search for the Default Route setting
4. Enter a new default path (starting with /) such as /docs and click Save

Deployments created after this change will now use the provided path as the default route.

To route paths to a new microfrontend, modify your microfrontends.json file. In the routing section for the project, add the new path:

{
  "$schema": "https://openapi.vercel.sh/microfrontends.json",
  "applications": {
    "web": {},
    "docs": {
      "routing": [
        {
          "paths": ["/docs", "/docs/:path*", "/new-path-to-route"]
        }
      ]
    }
  }
}

The routing for this new path will take effect when the code is merged and the deployment is live. You can test the routing changes in Preview or pre-Production to make sure it works as expected before rolling out the change to end users.

Additionally, if you need to revert, you can use Instant Rollback to rollback the project to a deployment before the routing change to restore the old routing rules.

You can use following path expressions in microfrontends.json:

• /path - Constant path.
• /:path - Wildcard that matches a single path segment.
• /:path/suffix - Wildcard that matches a single path segment with a constant path at the end.
• /prefix/:path* - Path that ends with a wildcard that can match zero or more path segments.
• /prefix/:path+ - Path that ends with a wildcard that matches one or more path segments.
• /:path(a|b) - Path is either /a or /b.
• /:path((?!a|b).*) - Path is any single path except /a or /b.
• /prefix-:path-suffix - Path that starts with /prefix-, ends with -suffix, and contains a single path segment.

The following are not supported:

• Conflicting or overlapping paths: Paths must uniquely map to one microfrontend
• Regular expressions not included above
• Wildcards that can match multiple path segments (+, *) that do not come at the end of the expression

To assert whether the path expressions will work for your path, use the validateRouting test utility to add unit tests that ensure paths get routed to the correct microfrontend.

If a microfrontend is not yet hosted on Vercel, you can create a new Vercel project to rewrite requests to the external application. You will then use this Vercel project in your microfrontends configuration on Vercel.

If you want to dynamically control the routing for a path, you can use flags to make sure that the change is safe before enabling the routing change permanently. Instead of automatically routing the path to the microfrontend, the request will be sent to the default application which then decides whether the request should be routed to the microfrontend.

This is compatible with the Flags SDK or it can be used with custom feature flag implementations.

1. Specify a flag name

   In your microfrontends.json file, add a name in the flag field for the group of paths:

   microfrontends.json

   {
     "$schema": "https://openapi.vercel.sh/microfrontends.json",
     "applications": {
       "web": {},
       "docs": {
         "routing": [
           {
             "flag": "name-of-feature-flag",
             "paths": ["/flagged-path"]
           }
         ]
       }
     }
   }

   Instead of being automatically routed to the docs microfrontend, requests to /flagged-path will now be routed to the default application to make the decision about routing.

2. Add microfrontends middleware

   The @vercel/microfrontends package uses middleware to route requests to the correct location for flagged paths and based on what microfrontends were deployed for your commit. Only the default application needs microfrontends middleware.

   You can add it to your Next.js application with the following code:

   middleware.ts

   import type { NextRequest } from 'next/server';
   import { runMicrofrontendsMiddleware } from '@vercel/microfrontends/next/middleware';
    
   export async function middleware(request: NextRequest) {
     const response = await runMicrofrontendsMiddleware({
       request,
       flagValues: {
         'name-of-feature-flag': async () => { ... },
       }
     });
     if (response) {
       return response;
     }
   }
    
   // Define routes or paths where this middleware should apply
   export const config = {
     matcher: [
       '/.well-known/vercel/microfrontends/client-config', // For prefetch optimizations for flagged paths
       '/flagged/path',
     ],
   };

   Your middleware matcher should include /.well-known/vercel/microfrontends/client-config. This endpoint is used by the client to know which application the path is being routed to for prefetch optimizations. The client will make a request to this well known endpoint to fetch the result of the path routing decision for this session.

   Make sure that any flagged paths are also configured in the middleware matcher so that middleware runs for these paths.

   Any function that returns Promise<boolean> can be used as the implementation of the flag. This also works directly with feature flags on Vercel.

   If the flag returns true, the microfrontends middleware will route the path to the microfrontend specified in microfrontends.json. If it returns false, the request will continue to be handled by the default application.

   We recommend setting up validateMiddlewareConfig and validateMiddlewareOnFlaggedPaths tests to prevent many common middleware misconfigurations.

To identify which microfrontend is responsible for serving a specific path, you can use the Deployment Summary or the Vercel Toolbar.

1. Go to the Project page for the default microfrontend application.
2. Click on the Deployment for the production deployment.
3. Open the Deployment Summary for the deployment.
4. Open up the Microfrontends accordion to see all paths that are served to that microfrontend. If viewing the default application, all paths for all microfrontends will be displayed.

1. On any page in the microfrontends group, open up the Vercel Toolbar.
2. Open up the Microfrontends Panel.
3. Look through the Directory of each microfrontend to find the application that serves the path. If no microfrontends match, the path is served by the default application.