single-spa Starter

This example demonstrates using single-spa with Module Federation on Vercel using Vercel Microfrontends. The application consists of two microfrontends that allows you to load multiple applications in a single page, enabling independent deployments and development.

Demo URL: https://microfrontends-single-spa-module-federation-root.labs.vercel.dev/

🚀 Deploy to Vercel

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

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/examples.git
   2
   cd microfrontends/single-spa

2. Install dependencies:

   1
   pnpm install

3. Start the development environment:

   1
   pnpm dev

   This command starts all applications simultaneously:

   • Root app
   • Content 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.

Key Components

1. Root Application (apps/root/)

   • Acts as the shell application and single-spa orchestrator
   • Dynamically imports components from content 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. Shared Packages (packages/)

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

Architecture Flow

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
    "single-spa-root-microfrontend": {
6
      "development": {
7
        "fallback": "microfrontends-single-spa-module-federation-root.vercel.app",
8
      },
9
    },
10
    "single-spa-content-microfrontend": {
11
      "routing": [
12
        {
13
          "paths": ["/_content/:path*"],
14
        },
15
      ],
16
    },
17
  },
18
}

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:

• single-spa-root-microfrontend: The root application that serves as the entry point for the microfrontend architecture. This is the default application of the Microfrontends group.
• single-spa-content-microfrontend: 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.

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 content application 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: '/_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.

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 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 { 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
        content: {
19
          type: 'module',
20
          name: 'content',
21
          entry: '/_content/remoteEntry.js',
22
        },
23
      },
24
      shared: {
25
        react: {
26
          singleton: true,
27
        },
28
        'react/': {
29
          singleton: true,
30
        },
31
        'react-dom': {
32
          singleton: true,
33
        },
34
        'react-dom/': {
35
          singleton: true,
36
        },
37
      },
38
    }) as Plugin[],
39
  ],
40
  build: {
41
    target: 'chrome89',
42
  },
43
});

The root application exposes some components, and it loads the and content application as a remote using Module Federation. The remotes configuration specifies the entry points for the remote applications, which are the remoteEntry.js files exposed by the content application.

Root application

The root application is the entry point for the microfrontend architecture. It is responsible for loading the 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('./header'),
8
  () => true,
9
);
10

11
registerApplication(
12
  'footer',
13
  () => import('./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 root 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
});

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 application as a microfrontend.

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.

📚 Documentation