Getting started with microfrontends

This quickstart guide will help you set up microfrontends on Vercel. Microfrontends can be used with different frameworks, and separate frameworks can be combined in a single microfrontends group.

• Have at least two Vercel projects created on Vercel that will be part of the same microfrontends group.

Before diving into implementation, it's helpful to understand these core concepts:

• Default app: The main application that manages the configuration file and handles routing decisions. The default app will also handle any request not handled by another microfrontend.
• Shared domain: All microfrontends appear under a single domain, allowing microfrontends to reference relative paths that point to the right environment automatically.
• Path-based routing: Requests are automatically directed to the appropriate microfrontend based on URL paths.
• Independent deployments: Teams can deploy their microfrontends without affecting other parts of the application.

1. Create a microfrontends group

   1. Navigate to your Vercel dashboard and make sure that you have selected your team from the scope selector.
   2. Visit the Settings tab.
   3. Find the Microfrontends tab from the Settings navigation menu.
   4. Click Create Group in the upper right corner.
   5. Follow the instructions to add projects to the microfrontends group and choose one of those applications to be the default application.

   Creating a microfrontends group and adding projects to that group does not change any behavior for those applications until you deploy a file to production.

2. Define

   Once the microfrontends group is created, you can define a file at the root in the default application. This configuration file is only needed in the default application, and it will control the routing for microfrontends. In this example, is the default application.

   Production behavior will not be changed until the file is merged and promoted, so you test in the Preview environment before deploying changes to production.

   On the Settings page for the new microfrontends group, click the Add Config button to copy the to your code.

   You can also create the configuration manually in code:

   Application names in should match the Vercel project names, see the microfrontends configuration documentation for more information.

   See the path routing documentation for details on how to configure the routing for your microfrontends.

3. Install the package

   In the directory of the microfrontend application, install the package using the following command:

   You need to perform this step for every microfrontend application.

4. Set up microfrontends with your framework

   Once the file has been added, Vercel will be able to start routing microfrontend requests to each microfrontend. However, the specifics of each framework, such as JS, CSS, and images, also need to be routed to the correct application.

   Any static asset not covered by the framework instructions above, such as images or any file in the directory, will also need to be added to the microfrontends configuration file or be moved to a path prefixed by the application's asset prefix. An asset prefix of (in , or in prior versions) is automatically set up by the Vercel microfrontends support.

5. Run through steps 3 and 4 for all microfrontend applications in the group

   Set up the other microfrontends in the group by running through steps 3 and 4 for every application.

6. Set up the local development proxy

   To provide a seamless local development experience, provides a microfrontends aware local development proxy to run alongside you development servers. This proxy allows you to only run a single microfrontend locally while making sure that all microfrontend requests still work.

   If you are using Turborepo, the proxy will automatically run when you run the development task for your microfrontend.

   If you don't use , you can set this up by adding a script to your like this:

   Next, use the auto-generated port in your command so that the proxy knows where to route the requests to:

   Once you have your application and the local development proxy running (either via or manually), visit the "Microfrontends Proxy" URL in your terminal output. Requests will be routed to your local app or your production fallback app. Learn more in the local development guide.

7. Deploy your microfrontends to Vercel

   You can now deploy your code to Vercel. Once live, you can then visit the domain for that deployment and visit any of the paths configured in . These paths will be served by the other microfrontend applications.

   In the example above, visiting the page will see the content from the microfrontend while visiting will see the content from the microfrontend.

   Microfrontends functionality can be tested in Preview before deploying the code to production.

• Learn how to use the package to manage local development.
• For polyrepo setups (separate repositories), see the polyrepo configuration guide.
• Route more paths to your microfrontends.
• To learn about other microfrontends features, visit the Managing Microfrontends documentation.
• Set up the Vercel Toolbar for access to developer tools to debug and manage microfrontends.

Microfrontends changes how paths are routed to your projects. If you encounter any issues, look at the Testing & Troubleshooting documentation or learn how to debug routing on Vercel.