Getting started with microfrontends

Microfrontends are available in Limited Beta to Enterprise plans

This quickstart guide will help you set up microfrontends on Vercel.

Choose a framework to optimize documentation to:

Prerequisites

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

Key concepts

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.

Set up microfrontends on Vercel

  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.

  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.

    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", "/docs/:path*"]
        }
      ]
    }
  }
}

    Application names in microfrontends.json should match the Vercel project names.

    If the application name differs from the name field in package.json for the application, you should either rename the name field in package.json to match or add the packageName field to the microfrontends configuration.

    microfrontends.json
        "docs": {
      "packageName": "name-from-package-json",
      "routing": [
        {
          "group": "docs",
          "paths": ["/docs", "/docs/:path*"]
        }
      ]
    }

  3. Install the @vercel/microfrontends package

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

    pnpm i @vercel/microfrontends

  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.

    To handle JavaScript and CSS assets in Next.js, add the withMicrofrontends wrapper to your next.config.js file.
    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);

    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.

    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-<application name> 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 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 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"
}

    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.

Next Steps

You've successfully set up your default application! From here, there are several paths to explore:

Last updated on June 25, 2025
Next
Account Management