Microfrontends Routing

Microfrontends routing determines which application handles a path and which deployment of that application receives the request. Vercel makes both routing decisions in its network infrastructure.

When Vercel receives a request to a domain that uses microfrontends, it reads the microfrontends.json file in the live deployment to determine which application handles the path. This happens within the same request. It is not a rewrite that results in a second outbound request to the child application's URL, so there is no additional network hop.

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

To route paths to a new microfrontend, modify the microfrontends.json file in your default application. In the routing section for the application that should handle the path, add the new path:

{
  "$schema": "https://openapi.vercel.sh/microfrontends.json",
  "applications": {
    "web": {},
    "docs": {
      "routing": [
        {
          "paths": ["/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.
• /\\(a\\) - Path is /(a), special characters in paths are escaped with a backslash.
• /:path(a|b) - Path is either /a or /b.
• /:path(a|\\(b\\)) - Path is either /a or /(b), special characters are escaped with a backslash.
• /: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.

An asset prefix is a unique prefix prepended to paths in URLs of static assets, like JavaScript, CSS, or images. This is needed so that URLs are unique across microfrontends and can be correctly routed to the appropriate project. Without this, these static assets may collide with each other and not work correctly.

When using withMicrofrontends, a default auto-generated asset prefix is automatically added. The default value is an obfuscated hash of the project name, like vc-ap-b3331f, in order to not leak the project name to users.

If you would like to use a human readable asset prefix, you can also set the asset prefix that is used in microfrontends.json.

"your-application": {
  "assetPrefix": "marketing-assets",
  "routing": [...]
}

JavaScript and CSS URLs are automatically prefixed with the asset prefix, but content in the public/ directory needs to be manually moved to a subdirectory with the name of the asset prefix.

Some functionality in the Vercel Dashboard, such as screenshots and links to the deployment domain, automatically links to the / path. Microfrontends deployments may not serve any content on the / path so that functionality may appear broken. You can set a default route in the dashboard so that the Vercel Dashboard instead always links to a valid route in the microfrontends deployment.

To update the default route, visit the Microfrontends Settings page.

1. Open Settings in the sidebar for your project and select Microfrontends
2. Search for the Default Route setting
3. 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.

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.

Vercel automatically determines which deployment to route a request to for the microfrontends projects in the same group. This allows developers to build and test any combination of microfrontends without having to build them all on the same commit.

Domains that use this microfrontends routing will have an M icon next to the name on the deployment page.

Vercel sets microfrontends routing for a domain when the domain is created or updated, such as when a deployment is built, promoted, or rolled back. For each project in the microfrontends group, the domain or URL type determines which deployment Vercel selects:

Domains assigned to the production environment always route to each project's current production deployment. This is the same deployment available through the project's production domain. If you roll back a microfrontend project, microfrontends routing uses the rollback deployment.

Domains assigned to a custom environment route requests to other microfrontends in custom environments with the same name. If a matching deployment is unavailable, Vercel uses the fallback environment configuration.

Automatically generated branch URLs and domains assigned to a Git branch route to the latest deployment for each project on that branch.

Projects in a monorepo share a Git repository, commits, and branches, so Vercel links their Preview Deployments using the shared commit. For Git-connected projects in separate repositories, open the default application's Settings, select Microfrontends, enable Cross-Repository Branch Routing, and save. Vercel then links the latest Preview Deployments whose branch names match.

For example, when you preview the new-checkout branch of one project, requests to other projects in the microfrontends group use their latest new-checkout Preview Deployments when available.

If no deployment exists for the project on the branch, Vercel routes requests using the fallback environment configuration.

Automatically generated deployment URLs preserve the state of the microfrontends group when Vercel creates the URL. For each project, Vercel first routes to a deployment from the same commit. If that deployment is unavailable, Vercel routes to the branch deployment captured when the URL was created, then to the fallback environment deployment captured at the same time.

Future deployments do not change these targets, so the deployment URL continues to represent the same point in time across the microfrontends group.

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.