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.
• If you're using a coding agent, install the microfrontends skill:

npx skills add vercel/microfrontends

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

• Default app: The main application that manages the microfrontends.json 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

   You can create a group using the CLI or the dashboard.

   Using the CLI:

   Run the following command and follow the interactive prompts to name the group, add projects, and choose the default application:

   terminal

   vercel microfrontends create-group

   Using the dashboard:

   1. Navigate to your Vercel dashboard and make sure that you have selected your team from the team switcher.
   2. Visit the Settings section in the sidebar.
   3. Find the Microfrontends section in the sidebar 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 microfrontends.json file to production.

2. Define microfrontends.json

   Once the microfrontends group is created, you can define a microfrontends.json 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, web is the default application.

   Production behavior will not be changed until the microfrontends.json 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 microfrontends.json to your code.

   You can also create the configuration manually in code:

   microfrontends.json

   {
     "$schema": "https://openapi.vercel.sh/microfrontends.json",
     "applications": {
       "web": {
         "development": {
           "fallback": "TODO: a URL in production that should be used for requests to apps not running locally"
         }
       },
       "docs": {
         "routing": [
           {
             "group": "docs",
             "paths": ["/docs/:path*"]
           }
         ]
       }
     }
   }

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

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

3. Install the @vercel/microfrontends package

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

   pnpmyarnnpmbun

   Terminal

   pnpm i @vercel/microfrontends

   Terminal

   yarn add @vercel/microfrontends

   Terminal

   npm i @vercel/microfrontends

   Terminal

   bun add @vercel/microfrontends

   You need to perform this step for every microfrontend application.

4. Set up microfrontends with your framework

   Once the microfrontends.json 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.

   Choose a framework to optimize documentation to

   To handle JavaScript and CSS assets in Next.js, add the withMicrofrontends wrapper to your next.config.js file.

   If this application also has routed pages in pages/, pass supportPagesRouter: true to withMicrofrontends(). This applies to mixed App Router and Pages Router applications.

   next.config.ts

   import type { NextConfig } from 'next';
   import { withMicrofrontends } from '@vercel/microfrontends/next/config';
    
   const nextConfig: NextConfig = {
     /* config options here */
   };
    
   export default withMicrofrontends(nextConfig);

   Use supportPagesRouter only when a Next.js microfrontend includes Pages Router routes. The option enables Pages Router support in the Next.js config transform. It changes Webpack chunk behavior to use deterministic module and chunk IDs, and it generates a build ID for child applications so Pages Router /_next/data requests route to the correct microfrontend. Applications that already set generateBuildId manually cannot use supportPagesRouter.

   The withMicrofrontends function will automatically add an asset prefix to the application so that you do not have to worry about that. Next.js applications that use basePath are not supported right now.

   vite.config.ts

   import { microfrontends } from '@vercel/microfrontends/experimental/vite';
    
   export default defineConfig({
     plugins: [microfrontends()],
   });

   Any static asset not covered by the framework instructions above, such as images or any file in the public/ 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 /vc-ap-<hash of application name> (in 2.0.0, or /vc-ap-<application name> 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, @vercel/microfrontends provides a microfrontends aware local development proxy to run alongside your 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 turbo, you can set this up by adding a script to your package.json like this:

   package.json

   "scripts": {
     "proxy": "microfrontends proxy --local-apps my-local-app-name"
   }

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

   package.json

   "scripts": {
     "dev": "next dev --port $(microfrontends port)"
   }

   Once you have your application and the local development proxy running (either via turbo 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 microfrontends.json. These paths will be served by the other microfrontend applications.

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

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

• Learn how to use the @vercel/microfrontends 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.