Microfrontends - Single SPA

Using this example, you can learn how to set up a microfrontend using single-spa with Module Federation on Vercel. This example demonstrates how to create a microfrontend architecture that allows you to load multiple applications in a single page, enabling independent deployments and development.

The example is available on GitHub at vercel-labs/microfrontends-single-spa-module-federation.

What You'll Learn

This example demonstrates real-world microfrontend patterns and best practices:

• 📊 Vercel Microfrontends: Production-ready deployment on Vercel's platform
• 🔗 Module Federation: Share code between applications at runtime using Webpack's Module Federation
• 🏗️ single-spa Integration: Orchestrate microfrontends with single-spa's lifecycle management
• ⚡ Runtime Code Sharing: Dynamically load and share components between applications
• 📦 Federated Components: Expose and consume React components across application boundaries
• 🚀 Independent Deployments: Deploy each microfrontend without affecting others
• 🎯 Team Autonomy: Enable teams to work independently while sharing code seamlessly
• 🔧 Vite & Tailwind: Modern build tools with utility-first CSS framework

Understanding the Architecture

This example implements a hybrid architecture combining single-spa for application orchestration with Module Federation for runtime code sharing:

Key Components

1. Root Application (apps/root/)

   • Acts as the shell application and single-spa orchestrator
   • Dynamically imports components from content and navigation remotes
   • Manages the overall application layout and routing with single-spa
   • Configures federated remotes and manages dependencies

2. Content Application (apps/content/)

   • Exposes content-related components through Module Federation
   • Provides federated page components wrapped with single-spa lifecycle
   • Maintains its own styling and component logic
   • Mounted as a single-spa application in the root

3. Navigation Application (apps/navigation/)

   • Exposes navigation components (header and footer) through Module Federation
   • Provides reusable navigation components for the entire application
   • Each component (header/footer) is registered as separate single-spa applications
   • Manages navigation state and user interactions

4. Shared Packages (packages/)

   • Common TypeScript configurations across all applications
   • Shared ESLint rules and formatting standards
   • Ensures consistency across all microfrontends

Architecture Flow

This hybrid approach provides:

• single-spa: Application lifecycle management and routing orchestration
• Module Federation: Efficient runtime code sharing and dependency optimization
• Best of both worlds: Robust application management with optimized code sharing

Getting Started

Prerequisites

To run the example, you will need the following prerequisites:

• Node.js installed on your machine.
• pnpm package manager installed.
• Git installed to clone the repository.

It is also recommended to have:

• Familiarity with single-spa and Module Federation concepts.
• Basic understanding of Vercel deployment process.
• A Vercel account to deploy the microfrontend applications.

Local Development Setup

Follow these steps to set up the example on your local machine. Make sure you have the prerequisites installed before proceeding.

1. Clone the repository:

   1
   git clone https://github.com/vercel-labs/microfrontends-single-spa-module-federation.git
   2
   cd microfrontends-single-spa-module-federation

2. Install dependencies:

   1
   pnpm install

3. Start the development environment:

   1
   pnpm dev

   This command starts all applications simultaneously:

   • Root app
   • Content app
   • Navigation app

4. Access the application:

   Open http://localhost:3024 in your browser to see the federated application where components from different microfrontends are composed together using single-spa and Module Federation.

Tech stack

This example uses the following technologies:

• singla-spa: A framework for building microfrontends that allows you to load multiple applications in a single page. Learn more about single-spa in the single-spa documentation.
• Module Federation: A feature of Webpack that allows you to share code between multiple applications at runtime. It enables the microfrontend architecture by allowing applications to dynamically load each other. Learn more about Module Federation in the Module Federation documentation.
• Tailwind CSS: A utility-first CSS framework that is used to style the microfrontend applications. Learn more about Tailwind CSS in the Tailwind CSS documentation.
• Vercel: A platform for deploying and hosting web applications, which provides features for managing microfrontends. Learn more about Vercel in the Vercel documentation.
• pnpm: A fast and efficient package manager that is used to manage dependencies in this example. Learn more about pnpm in the pnpm documentation.
• Turborepo: A high-performance build system that is used to manage the monorepo structure of the example. Learn more about Turborepo in the Turborepo documentation.
• Vite: A fast build tool that is used to build the microfrontend applications. Learn more about Vite in the Vite documentation.

Microfrontends configuration

The microfrontends are configured using the microfrontends.json file. This file defines the applications and their routing. The example uses the following configuration:

1
// apps/root/microfrontends.json
2
{
3
  "$schema": "https://openapi.vercel.sh/microfrontends.json",
4
  "applications": {
5
    "microfrontends-single-spa-module-federation-root": {
6
      "development": {
7
        "fallback": "microfrontends-single-spa-module-federation-root.vercel.app",
8
      },
9
    },
10
    "microfrontends-single-spa-module-federation-content": {
11
      "routing": [
12
        {
13
          "paths": ["/_content/:path*"],
14
        },
15
      ],
16
    },
17
    "microfrontends-single-spa-module-federation-navigation": {
18
      "routing": [
19
        {
20
          "paths": ["/_navigation/:path*"],
21
        },
22
      ],
23
    },
24
  },
25
}

This configuration is defined in the root application, which is the default application of the microfrontends group. The microfrontends.json file specifies the applications and their routing paths. The development.fallback field is used to specify a fallback URL. See more details on how to manage your microfrontends in the Managing Microfrontends documentation.

The microfrontends.json in this example defines three applications:

• microfrontends-single-spa-module-federation-root: The root application that serves as the entry point for the microfrontend architecture. This is the default application of the Microfrontends group.
• microfrontends-single-spa-module-federation-content: A microfrontend application that handles content-related functionality. It is routed to paths starting with /_content/. The application will provide the landing page content for our example.
• microfrontends-single-spa-module-federation-navigation: A microfrontend application that handles navigation functionality. It is routed to paths starting with /_navigation/. The application will provide the navigation components.

As we don't specify a specific local Microfrontends proxy port, the local Microfrontends proxy will run on port 3024 by default. You can change this by setting localProxyPort in the microfrontends.json file.

Vite configuration

To make Microfrontends and Module Federation work, we need to configure Vite in each microfrontend application.

For the navigation and content applications providing the Module Federation remotes for the root application, we need to set up the Vite configuration as follows:

1
import { defineConfig, type Plugin } from 'vite';
2
import { federation } from '@module-federation/vite';
3
import tailwindcss from '@tailwindcss/vite';
4
import { microfrontends } from '@vercel/microfrontends/experimental/vite';
5
import react from '@vitejs/plugin-react';
6

7
export default defineConfig({
8
  plugins: [
9
    tailwindcss(),
10
    microfrontends({
11
      basePath: '/_navigation',
12
    }) as Plugin,
13
    react(),
14
    federation({
15
      name: 'navigation',
16
      manifest: true,
17
      filename: 'remoteEntry.js',
18
      exposes: {
19
        './header': './src/header/index.tsx',
20
        './footer': './src/footer/index.tsx',
21
      },
22
      shared: {
23
        react: {
24
          singleton: true,
25
        },
26
        'react/': {
27
          singleton: true,
28
        },
29
        'react-dom': {
30
          singleton: true,
31
        },
32
        'react-dom/': {
33
          singleton: true,
34
        },
35
      },
36
    }) as Plugin[],
37
  ],
38
  build: {
39
    target: 'chrome89',
40
  },
41
});

The only difference between the navigation and content applications is the basePath in the microfrontends plugin configuration, the name of the Module Federation remote and the exposed modules. The basePath is set to /_navigation for the navigation application and to /_content for the content application.

1
import { defineConfig, type Plugin } from 'vite';
2
import { federation } from '@module-federation/vite';
3
import tailwindcss from '@tailwindcss/vite';
4
import { microfrontends } from '@vercel/microfrontends/experimental/vite';
5
import react from '@vitejs/plugin-react';
6

7
export default defineConfig({
8
  plugins: [
9
    tailwindcss(),
10
    microfrontends({
11
      basePath: '/_content',
12
    }) as Plugin,
13
    react(),
14
    federation({
15
      name: 'content',
16
      manifest: true,
17
      filename: 'remoteEntry.js',
18
      exposes: {
19
        './landing': './src/landing.tsx',
20
      },
21
      shared: {
22
        react: {
23
          singleton: true,
24
        },
25
        'react/': {
26
          singleton: true,
27
        },
28
        'react-dom': {
29
          singleton: true,
30
        },
31
        'react-dom/': {
32
          singleton: true,
33
        },
34
      },
35
    }) as Plugin[],
36
  ],
37
  build: {
38
    target: 'chrome89',
39
  },
40
});

Both configurations use the @module-federation/vite plugin to set up Module Federation and the @vercel/microfrontends/experimental/vite plugin to enable microfrontends support. The federation plugin is used to expose the components of the microfrontend applications, while the microfrontends plugin is used to configure the base path for the microfrontend routing.

For both the navigation and content applications, we expose the components that will be used by the root application. The navigation application exposes a header and footer component, while the content application exposes a landing component.

React and React DOM are shared as singletons to ensure that the same instance is used across the microfrontends. This is important for maintaining a consistent state and avoiding issues with multiple instances of React.

The additional specification for a build.target is set to chrome89 to ensure compatibility with the features used in the microfrontends. In this case we need top-level await support, which is available in Chrome 89 and later.

For the root application, we need to set up the Vite configuration to load the microfrontends and use the exposed components from the navigation and content applications:

1
import { defineConfig, type Plugin } from 'vite';
2
import { federation } from '@module-federation/vite';
3
import tailwindcss from '@tailwindcss/vite';
4
import { microfrontends } from '@vercel/microfrontends/experimental/vite';
5
import { vercelToolbar } from '@vercel/toolbar/plugins/vite';
6
import react from '@vitejs/plugin-react';
7

8
export default defineConfig({
9
  plugins: [
10
    tailwindcss(),
11
    microfrontends() as Plugin,
12
    vercelToolbar(),
13
    react(),
14
    federation({
15
      name: 'root',
16
      manifest: true,
17
      remotes: {
18
        navigation: {
19
          type: 'module',
20
          name: 'navigation',
21
          entry: '/_navigation/remoteEntry.js',
22
        },
23
        content: {
24
          type: 'module',
25
          name: 'content',
26
          entry: '/_content/remoteEntry.js',
27
        },
28
      },
29
      shared: {
30
        react: {
31
          singleton: true,
32
        },
33
        'react/': {
34
          singleton: true,
35
        },
36
        'react-dom': {
37
          singleton: true,
38
        },
39
        'react-dom/': {
40
          singleton: true,
41
        },
42
      },
43
    }) as Plugin[],
44
  ],
45
  build: {
46
    target: 'chrome89',
47
  },
48
});

The root application doesn't expose any components, but it loads the navigation and content applications as remotes using Module Federation. The remotes configuration specifies the entry points for the remote applications, which are the remoteEntry.js files exposed by the navigation and content applications.

As we are using Vite for the navigation and content applications providing the Module Federation remotes, we use remotes specified with type: 'module' to load the remote applications. This allows us to use the native ES module loading capabilities of the browser, which is supported by Vite.

The entry paths for the remotes are set to /_navigation/remoteEntry.js and /_content/remoteEntry.js, which correspond to the base paths defined in the microfrontends.json file. As we are using Vercel Microfrontends solution and in this example we are using client-side rendering, we can use relative URLs for the remotes. This allows the root application to dynamically load the components from the navigation and content applications at runtime. The routing will be managed by Vercel Microfrontends, which will ensure that the correct application is loaded based on the path.

Root application

The root application is the entry point for the microfrontend architecture. It is responsible for loading the navigation and content remotes and rendering their components as single-spa applications.

To create a layout for the root application using single-spa, we can use the following HTML structure:

1
<!doctype html>
2
<html lang="en">
3
  <head>
4
    <meta charset="UTF-8" />
5
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
    <title>Company Landing Page</title>
7
    <link rel="stylesheet" href="./src/globals.css" />
8
    <script type="module" src="./src/index.ts"></script>
9
  </head>
10
  <body className="flex min-h-screen flex-col">
11
    <div id="single-spa-application:header"></div>
12
    <div id="single-spa-application:content"></div>
13
    <div id="single-spa-application:footer"></div>
14
  </body>
15
</html>

To register each application with single-spa, we can use the following code in the src/index.ts file of the root application:

1
import { mountVercelToolbar } from '@vercel/toolbar/vite';
2
import { registerApplication, start } from 'single-spa';
3
import './globals.css';
4

5
registerApplication(
6
  'header',
7
  () => import('navigation/header'),
8
  () => true,
9
);
10

11
registerApplication(
12
  'footer',
13
  () => import('navigation/footer'),
14
  () => true,
15
);
16

17
registerApplication(
18
  'content',
19
  () => import('content/landing'),
20
  () => true,
21
);
22

23
start();
24
mountVercelToolbar();

We register each single-spa application using the registerApplication function. Each application is registered with a name, a loading function that imports the remote component using dynamic ES module import, and an activity function that determines when the application should be active based on the current route, which will be always true in the case of this example.

Remote applications

In the remote applications, we are using single-spa-react to create a React component that will be rendered by single-spa. The content application provides the main page content, while the navigation application provides the header and footer components.

We need to define the bootstrap, mount, and unmount functions for each component. These functions are used by single-spa to manage the lifecycle of the applications.

1
import React from 'react';
2
import ReactDOMClient from 'react-dom/client';
3
import singleSpaReact from 'single-spa-react';
4
import './globals.css';
5

6
function Landing(): React.JSX.Element {
7
  return <>{/* ... */}</>;
8
}
9

10
export const { bootstrap, mount, unmount } = singleSpaReact({
11
  React,
12
  ReactDOMClient,
13
  rootComponent: Landing,
14
  errorBoundary() {
15
    return <></>;
16
  },
17
});

For the navigation application, we define the header and footer components similarly.

1
// ...
2
export const { bootstrap, mount, unmount } = singleSpaReact({
3
  React,
4
  ReactDOMClient,
5
  rootComponent: Header,
6
  errorBoundary() {
7
    return <></>;
8
  },
9
});

1
// ...
2
export const { bootstrap, mount, unmount } = singleSpaReact({
3
  React,
4
  ReactDOMClient,
5
  rootComponent: Footer,
6
  errorBoundary() {
7
    return <></>;
8
  },
9
});

The difference being which rootComponent is used for each application. The Landing component in the content application, and the Header and Footer components in the navigation application.

Local development

With everything needed set up, you can now run the microfrontend applications locally. The root application will be available at http://localhost:3024, and it will load the content and navigation applications as microfrontends.

To start a development server for each application, we use a dev npm script in each application's package.json file. The dev script uses Vite to start the development server for the application and also specifies the port to run on when using the Microfrontends proxy.

1
// apps/root/package.json
2
{
3
  "scripts": {
4
    "build": "vite build",
5
    "dev": "vite --port $(microfrontends port)",
6
    "start": "vite preview --port $(microfrontends port)",
7
  },
8
}

Run the following command in the root directory of the cloned repository to start the development server and the Microfrontends proxy:

1
pnpm dev

This command will start all the applications in the monorepo and also starts the Microfrontends proxy on port 3024.

🚀 Deploy to Vercel

Deploy each microfrontend independently to experience the full power of distributed development:

Deployment Strategy

Independent Deployment Benefits

Each microfrontend can be deployed independently, enabling:

• Faster deployments: Only the changed microfrontend needs redeployment
• Reduced risk: Deployments are isolated and can't break other parts
• Team autonomy: Teams can deploy on their own schedule
• Rollback flexibility: Roll back individual microfrontends without affecting others

Step-by-Step Deployment Guide

1. Fork the repository: Create your own copy of the repository on GitHub.

2. Set up Vercel projects: Create separate Vercel projects for each microfrontend:

   • Fork this repository to your GitHub account
   • In Vercel, create a new project for each application (root, content, navigation)
   • Connect each project to your forked repository
   • Set the root directory for each project (apps/root, apps/content, apps/navigation)

3. Configure Microfrontends group:

   • In the Vercel dashboard, create a new Microfrontends group
   • Add all three applications to the group
   • Set the root application as the default application

4. Environment configuration:

   • Ensure each application has the correct build settings
   • Verify that the microfrontends.json file is properly configured
   • Set up any required environment variables

5. Deploy and verify:

   • Deploy each application independently
   • Test the integration by accessing the root application URL
   • Verify that all microfrontends load correctly and communicate properly

Vercel Configuration

Each application includes optimized Vercel configuration:

• Framework detection: Automatic Vite optimization
• Build settings: Turborepo-aware build commands with Module Federation support
• Environment variables: Proper environment isolation for each microfrontend
• Edge functions: Optimal performance at the edge with Vercel's global CDN

Production URLs

Once deployed, your applications will be accessible at URLs similar to:

• Root: https://your-root-app.vercel.app
• Content: https://your-content-app.vercel.app
• Navigation: https://your-navigation-app.vercel.app

The root application will automatically load the content and navigation microfrontends based on the routing configuration in microfrontends.json.

The example is deployed to Vercel at https://vercel-microfrontends-single-spa.vercel.app already for you to check out.

Development Workflow

Working with Individual Microfrontends

You can develop microfrontends in isolation:

1
# Work on the root application only
2
cd apps/root
3
pnpm dev
4

5
# Work on the content application only
6
cd apps/content
7
pnpm dev
8

9
# Work on the navigation application only
10
cd apps/navigation
11
pnpm dev

Building and Testing

1
# Build all applications
2
pnpm build
3

4
# Run linting across all apps
5
pnpm lint
6

7
# Type check all applications
8
pnpm typecheck
9

10
# Run all quality checks
11
pnpm checks

Adding New Federated Components

1. Create the component in your remote application
2. Expose it through Module Federation in vite.config.ts:

   1
   exposes: {
   2
     './newComponent': './src/path/to/component.tsx'
   3
   }

3. Add TypeScript declarations in the container app's global.d.ts:

   1
   declare module 'remoteName/newComponent' {
   2
     const Component: React.ComponentType;
   3
     export default Component;
   4
   }

4. Import and use in the container application:

   1
   import NewComponent from 'remoteName/newComponent';

Best Practices Implemented

🎯 Consistent Development Experience

• Shared TypeScript configuration ensures type safety across all federated modules
• Common ESLint rules maintain code quality standards
• Unified Prettier configuration for consistent formatting

🔧 Build Optimization

• Turborepo orchestrates builds efficiently with caching
• Module Federation optimizes shared dependencies automatically
• Independent builds enable faster CI/CD pipelines

🎨 UI Consistency

• Shared component patterns across federated modules
• Consistent design tokens and styling approach with Tailwind CSS
• Federated components maintain design system compliance

🚀 Performance Optimization

• Code splitting at the microfrontend level with Module Federation
• Shared chunk optimization for common dependencies (React, React DOM)
• Runtime loading optimization for federated modules
• Top-level await support for modern browser features

Troubleshooting

Common Issues and Solutions

Module Federation loading errors:

1
# Ensure all applications are running
2
pnpm dev

TypeScript errors with federated modules:

1
# Verify TypeScript declarations in global.d.ts
2
# Ensure module names match the federation configuration

Build failures:

1
# Run type checking to identify issues
2
pnpm typecheck
3

4
# Verify all federated modules are built correctly
5
pnpm build

Single-spa vs Module Federation Comparison

This example combines both single-spa and Module Federation for optimal microfrontend architecture:

Benefits of the combined approach:

• single-spa handles application lifecycle and routing
• Module Federation enables efficient code sharing and dependency management
• Best of both worlds: robust orchestration with optimized runtime sharing

Architecture Benefits

Team Autonomy

• Independent development: Teams can work on separate microfrontends without coordination
• Technology flexibility: Each microfrontend can use different versions of dependencies
• Deployment independence: Deploy changes without affecting other teams

Scalability

• Horizontal scaling: Add new microfrontends without modifying existing ones
• Performance isolation: Poor performance in one microfrontend doesn't affect others
• Code organization: Clear separation of concerns across team boundaries

Maintainability

• Isolated testing: Test each microfrontend independently
• Gradual migrations: Update or rewrite microfrontends incrementally
• Clear ownership: Each team owns their microfrontend completely

Toolbar

The Vercel Toolbar is included in the root application to provide insights and debugging capabilities for the microfrontend applications. The toolbar can be mounted using the mountVercelToolbar function from the @vercel/toolbar/vite package.

Learn more about the Vercel Toolbar in the Vercel Toolbar documentation.

Conclusion

This example demonstrates how to set up a microfrontend architecture using single-spa with Module Federation on Vercel. By following the steps outlined in this guide and the provided repo on GitHub, you can create a scalable and maintainable microfrontend application that allows for independent deployments and development.

📚 Documentation