Microfrontends local development

To provide a seamless local development experience, 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.

Microfrontends allow teams to split apart an application and only run an individual microfrontend to improve developer velocity. A downside of this approach is that requests to the other microfrontends won't work unless that microfrontend is also running locally. The microfrontends proxy solves this by intelligently falling back to route microfrontend requests to production for those applications that are not running locally.

For example, if you have two microfrontends and :

A developer working on only runs the Docs microfrontend, while a developer working on only runs the Web microfrontend. If a Docs developer wants to test a transition between and , they need to run both microfrontends locally. This is not the case with the microfrontends proxy as it routes requests to to the instance of Web that is running in production.

Therefore, the microfrontends proxy allows developers to run only the microfrontend they are working on locally and be able to test paths in other microfrontends.

• Set up your microfrontends on Vercel
• All applications that are part of the microfrontend have listed as a dependency
• Optional: Turborepo in your repository

1. Application setup

   In order for the local proxy to redirect traffic correctly, it needs to know which port each application's development server will be using. To keep the development server and the local proxy in sync, you can use the command provided by which will automatically assign a port.

   If you would like to use a specific port for each application, you may configure that in :

   The field may also contain a host or protocol (for example, or ).

   If the name of the application in (such as or ) does not match the name used in , you can also set the field for the application so that the local development proxy knows if the application is running locally.

2. Starting local proxy

   The local proxy is started automatically when running a microfrontend development task with . By default a microfrontend application's script is selected as the development task, but this can be changed with the field in .

   Running will start the microfrontends development server along with a local proxy that routes all requests for to the configured production host.

   This requires version or or newer of the package.

3. Setting up your monorepo

   1. Option 1: Adding Turborepo to a monorepo

      Turborepo is the suggested way to work with microfrontends as it provides a managed way for running multiple applications and a proxy simultaneously.

      If you don't already use Turborepo in your monorepo, can infer a configuration from your . This allows you to start using Turborepo in your monorepo without any additional configuration.

      To get started, follow the Installing guide.

      Once you have installed , run your development tasks using instead of your package manager. This will start the local proxy alongside the development server.

      You can start the development task for the Web microfrontend by running . Review Turborepo's filter documentation for details about filtering tasks.

      For more information on adding Turborepo to your repository, review adding Turborepo to an existing repository.

   2. Option 2: Using without Turborepo

      If you do not want to use Turborepo, you can invoke the proxy directly.

      Review Understanding the proxy command for more details.

4. Accessing the microfrontends proxy

   When testing locally, you should use the port from the microfrontends proxy to test your application. For example, if runs on port and the microfrontends proxy is on port , you should visit to test all parts of their application.

   You can change the port of the local development proxy by setting in :

To debug issues with microfrontends locally, enable microfrontends debug mode when running your application. Details about changes to your application, such as environment variables and rewrites, will be printed to the console. If using the local development proxy, the logs will also print the name of the application and URL of the destination where each request was routed to.

1. Set an environment variable
2. Or, set to in when calling

If you're working with a polyrepo setup where microfrontends are distributed across separate repositories, you'll need additional configuration since the file won't be automatically detected.

First, ensure that each microfrontend repository has access to the shared configuration:

• Option 1: Use the Vercel CLI to fetch the configuration:

  This command will download the file from your default application to your local repository.

  If you haven't linked your project yet, the command will prompt you to link your project to Vercel first.

  This command requires the Vercel CLI 44.2.2 to be installed.

• Option 2: Set the environment variable with a path pointing to your file:

  You can also add this to your file:

In a polyrepo setup, you'll need to start each microfrontend application separately since they're in different repositories. Unlike monorepos where Turborepo can manage multiple applications, polyrepos require manual coordination:

1. Start your local microfrontend application

   Start your microfrontend application with the proper port configuration. Follow the Application setup instructions to configure your development script with the command.

2. Run the microfrontends proxy

   In the same or a separate terminal, start the microfrontends proxy:

   Make sure to specify the correct application name that matches your configuration.

3. Access your application

   Visit the proxy URL shown in the terminal output (typically ) to test the full microfrontends experience. This URL will route requests to your local app or production fallbacks as configured.

Since you're working across separate repositories, you'll need to manually start any other microfrontends you want to test locally, each in their respective repository.

When setting up your monorepo without turborepo, the command used inside the scripts has the following specifications:

• is an executable provided by the package.
  • You can also run it with a command like (or the equivalent for your package manager), as long as it's from a context where the package is installed.
• is a sub-command to run the local proxy.
• is the path to your microfrontends configuration file. If you have a monorepo, you may also leave this out and the script will attempt to locate the file automatically.
• is followed by a space separated list of the applications running locally. For the applications provided in this list, the local proxy will route requests to those local applications. Requests for other applications will be routed to the URL specified in your microfrontends configuration for that app.

For example, if you are running the Web and Docs microfrontends locally, this command would set up the local proxy to route requests locally for those applications, and requests for the remaining applications to their fallbacks:

We recommend having a proxy command associated with each application in your microfrontends group. For example:

• If you run to start up your application for local development, set up as well
  • This should pass so it sends requests to the local application, and everything else to the fallback.

Therefore, you can run and to get the full microfrontends setup running locally.

To fall back to a Vercel deployment protected with Deployment Protection, set an environment variable with the value of the Protection Bypass for Automation.

You must name the environment variable . The name is transformed to be uppercase, and any non letter or number is replaced with an underscore.

For example, the env var name for an app named would be: .

1. Enable the Protection Bypass for Automation for your project

   1. Navigate to the Vercel project for the protected fallback deployment
   2. Click on the Settings tab
   3. Click on Deployment Protection
   4. If not enabled, create a new Protection Bypass for Automation
   5. Copy the value of the secret

2. Set the environment variable in the default app project

   1. Navigate to the Vercel project for the default application (may or may not be the same project)
   2. Click on the Settings tab
   3. Click on Environment Variables
   4. Add a new variable with the name (e.g. ) and the value of the secret from the previous step
   5. Set the selected environments for the variable to
   6. Click on Save

3. Import the secret using vc env pull

   1. Ensure you have vc installed
   2. Navigate to the root of the default app folder
   3. Run to authenticate with Vercel
   4. Run to link the folder to the Vercel project
   5. Run to pull the secret into your local environment

4. Update your README.md

   Include the previous step in your repository setup instructions, so that other users will also have the secret available.