Single-SPA Framework: A Comprehensive Guide to Micro-Frontend Orchestration

In today's rapidly evolving web development landscape, monolithic frontends are increasingly struggling to keep pace with the demands of growing applications and distributed teams. The micro-frontend architecture has emerged as a powerful solution to these challenges, enabling developers to build complex user interfaces as a collection of independent, deployable, and maintainable components. This approach fosters team autonomy, promotes code reusability, and simplifies the overall development process. Among the various frameworks available for micro-frontend orchestration, single-SPA stands out as a versatile and robust choice.

What are Micro-Frontends?

Micro-frontends are an architectural style where a frontend app is decomposed into smaller, independent, and self-contained units (micro-frontends). Each micro-frontend can be developed, deployed, and maintained by separate teams. Think of it as a composition of several mini-applications working together to form a cohesive user experience.

Key characteristics of micro-frontends include:

• Technology Agnostic: Each micro-frontend can be built using different frameworks and technologies (React, Angular, Vue.js, etc.)
• Independent Deployability: Micro-frontends can be deployed independently without affecting other parts of the application.
• Autonomous Teams: Different teams can own and maintain different micro-frontends, fostering autonomy and faster development cycles.
• Code Reusability: Common components and libraries can be shared across micro-frontends.
• Improved Scalability and Maintainability: Smaller, independent units are easier to scale, maintain, and update compared to a large monolithic application.

Why Choose Single-SPA?

Single-SPA is a JavaScript framework that facilitates the orchestration of multiple JavaScript applications (micro-frontends) within a single browser page. It doesn't prescribe any specific technology stack for the micro-frontends themselves, allowing teams to choose the tools best suited for their needs. This framework acts as a meta-framework, providing the infrastructure for loading, unloading, and managing the lifecycle of different micro-frontends.

Here's why single-SPA is a popular choice for micro-frontend orchestration:

• Framework Agnosticism: single-SPA can be used with virtually any JavaScript framework, including React, Angular, Vue.js, Svelte, and more. This flexibility allows teams to adopt micro-frontends incrementally without rewriting their existing applications.
• Gradual Adoption: You can gradually migrate a monolithic application to a micro-frontend architecture, starting with small, isolated features.
• Code Sharing: single-SPA allows you to share code and dependencies between micro-frontends, reducing redundancy and improving consistency.
• Lazy Loading: Micro-frontends are loaded on demand, improving initial page load time and overall performance.
• Simplified Deployment: Independent deployment of micro-frontends allows for faster release cycles and reduced risk.
• Robust Lifecycle Management: single-SPA provides a well-defined lifecycle for each micro-frontend, ensuring that they are properly initialized, mounted, unmounted, and destroyed.

Key Concepts in Single-SPA

To effectively use single-SPA, it's crucial to understand its core concepts:

• Single-SPA Config: The main JavaScript file that bootstraps the single-SPA application. It's responsible for registering micro-frontends and defining the routing logic. This often includes the root component that manages everything.
• Micro-frontends: Independent JavaScript applications that are registered with the single-SPA config. Each micro-frontend is responsible for rendering a specific part of the user interface.
• Parcels: Reusable components that can be shared between micro-frontends. Parcels are useful for creating common UI elements or business logic that is needed in multiple parts of the application.
• Root Config: The main application shell that loads and orchestrates the micro-frontends. It's responsible for handling routing, global state management, and communication between micro-frontends.
• Activity Functions: JavaScript functions that determine when a micro-frontend should be active (mounted) or inactive (unmounted). These are typically based on URL routes or other application state.

Implementing Single-SPA: A Step-by-Step Guide

Let's walk through a basic example of setting up a single-SPA application with two micro-frontends: one built with React and the other with Vue.js.

Step 1: Set up the Single-SPA Config

First, create a new directory for your single-SPA application and initialize a Node.js project:

            mkdir single-spa-example
cd single-spa-example
npm init -y
            

              
                Copy
              
            
          

Next, install the necessary dependencies:

            npm install single-spa import-map-overrides
            

              
                Copy
              
            
          

Create an `index.html` file in the root directory:

            <!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Single-SPA Example</title>
  <meta name="importmap-type" content="systemjs-importmap">
  <script type="systemjs-importmap">
    {
      "imports": {
        "single-spa": "https://cdn.jsdelivr.net/npm/single-spa@5.9.0/lib/single-spa.min.js",
        "react": "https://cdn.jsdelivr.net/npm/react@16.13.1/umd/react.production.min.js",
        "react-dom": "https://cdn.jsdelivr.net/npm/react-dom@16.13.1/umd/react-dom.production.min.js",
        "vue": "https://cdn.jsdelivr.net/npm/vue@2.6.12/dist/vue.min.js"
      }
    }
  </script>
  <script src="https://cdn.jsdelivr.net/npm/import-map-overrides@2.2.0/dist/import-map-overrides.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/systemjs@6.8.3/dist/system.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/systemjs@6.8.3/dist/extras/named-exports.js"></script>

</head>
<body>
  <noscript>
    You need to enable JavaScript to run this app.
  </noscript>
  <div id="root"></div>
  <script>
    System.import('single-spa-config');
  </script>
  <import-map-overrides-full show-when-local-storage="devtools"></import-map-overrides-full>
</body>
</html>
            

              
                Copy
              
            
          

This `index.html` file sets up the SystemJS module loader, import maps, and the single-SPA config. The import maps define the URLs for the dependencies used by the micro-frontends.

Create a `single-spa-config.js` file:

            import * as singleSpa from 'single-spa';

singleSpa.registerApplication(
  'react-app',
  () => System.import('react-app'),
  location => location.pathname.startsWith('/react')
);

singleSpa.registerApplication(
  'vue-app',
  () => System.import('vue-app'),
  location => location.pathname.startsWith('/vue')
);

singleSpa.start();
            

              
                Copy
              
            
          

This file registers two micro-frontends: `react-app` and `vue-app`. The `activityFunction` determines when each micro-frontend should be active based on the URL.

Step 2: Create the React Micro-Frontend

Create a new directory for the React micro-frontend:

            mkdir react-app
cd react-app
npx create-react-app .
npm install single-spa-react
            

              
                Copy
              
            
          

Modify the `src/index.js` file to use `single-spa-react`:

            import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import reportWebVitals from './reportWebVitals';
import singleSpaReact from 'single-spa-react';

const lifecycles = singleSpaReact({
  React,
  ReactDOM,
  rootComponent: App,
  errorBoundary(err, info, props) {
    // Customize the root error boundary for your microfrontend here.
    return (<h1>Error</h1>);
  },
});

export const { bootstrap, mount, unmount } = lifecycles;

// If you want to start measuring performance in your app, pass a function
// to log results (for example: reportWebVitals(console.log))
// or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
reportWebVitals();

            

              
                Copy
              
            
          

Create a `public/index.html` file (if it doesn't exist) and ensure the `root` div is present:

            <!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="theme-color" content="#000000" />
    <meta
      name="description"
      content="Web site created using create-react-app"
    />
    <link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />
    <!--
      manifest.json provides metadata used when your web app is installed on a
      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
    -->
    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
    <!--
      Notice the use of %PUBLIC_URL% in the tags above.
      It will be replaced with the URL of the `public` folder during the build.
      Only files inside the `public` folder can be referenced from the HTML.

      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
      work correctly both with client-side routing and a non-root public URL.
      Learn how to configure a non-root public URL by running `npm run build`.
    -->
    <title>React App</title>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div id="root"></div>
    <!--
      This HTML file is a template.
      If you open it directly in the browser, you will see an empty page.

      You can add webfonts, meta tags, or analytics to this file.
      The build step will place the bundled scripts into the <body> tag.

      To begin the development, run `npm start` or `yarn start`.
      To create a production bundle, use `npm run build` or `yarn build`.
    -->
  </body>
</html>
            

              
                Copy
              
            
          

Modify `App.js` to show some custom text to easily verify our work:

            import React from 'react';
import logo from './logo.svg';
import './App.css';

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          This is the React Micro-Frontend!
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
      </header>
    </div>
  );
}

export default App;

            

              
                Copy
              
            
          

Build the React micro-frontend:

            npm run build
            

              
                Copy
              
            
          

Rename the `build` directory to `react-app` and place it in the root of the single-SPA application. Then, inside the `react-app` directory create a `react-app.js` file with the content of the `build/static/js` file. If there are more js files in the `static/js` directory, include them as well.

Update the import map in `index.html` to point to the React micro-frontend:

            {
  "imports": {
    "single-spa": "https://cdn.jsdelivr.net/npm/single-spa@5.9.0/lib/single-spa.min.js",
    "react": "https://cdn.jsdelivr.net/npm/react@16.13.1/umd/react.production.min.js",
    "react-dom": "https://cdn.jsdelivr.net/npm/react-dom@16.13.1/umd/react-dom.production.min.js",
    "vue": "https://cdn.jsdelivr.net/npm/vue@2.6.12/dist/vue.min.js",
    "react-app": "/react-app/react-app.js"
  }
}
            

              
                Copy
              
            
          

Step 3: Create the Vue.js Micro-Frontend

Create a new directory for the Vue.js micro-frontend:

            mkdir vue-app
cd vue-app
npx @vue/cli create .
npm install single-spa-vue --save
            

              
                Copy
              
            
          

During the Vue CLI setup, choose the default preset or customize it as needed.

Modify the `src/main.js` file to use `single-spa-vue`:

            import Vue from 'vue'
import App from './App.vue'
import singleSpaVue from 'single-spa-vue';

Vue.config.productionTip = false

const vueLifecycles = singleSpaVue({
  Vue,
  appOptions: {
    el: '#vue-app',
    render: h => h(App)
  }
});

export const bootstrap = vueLifecycles.bootstrap;
export const mount = vueLifecycles.mount;
export const unmount = vueLifecycles.unmount;
            

              
                Copy
              
            
          

Modify `App.vue` to show some custom text to easily verify our work:

            <template>
  <div id="app">
    <img alt="Vue logo" src="./assets/logo.png">
    <p>This is the <b>Vue Micro-Frontend</b>!</p>
    <HelloWorld msg="Welcome to Your Vue.js App"/>
  </div>
</template>

<script>
import HelloWorld from './components/HelloWorld.vue'

export default {
  name: 'App',
  components: {
    HelloWorld
  }
}
</script>

<style>
#app {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-align: center;
  color: #2c3e50;
}
</style>

            

              
                Copy
              
            
          

Build the Vue.js micro-frontend:

            npm run build
            

              
                Copy
              
            
          

Rename the `dist` directory to `vue-app` and place it in the root of the single-SPA application. Then, inside the `vue-app` directory create a `vue-app.js` file with the content of the `dist/js/app.js` file. If there are more js files in the `dist/js` directory, include them as well.

Update the import map in `index.html` to point to the Vue.js micro-frontend:

            {
  "imports": {
    "single-spa": "https://cdn.jsdelivr.net/npm/single-spa@5.9.0/lib/single-spa.min.js",
    "react": "https://cdn.jsdelivr.net/npm/react@16.13.1/umd/react.production.min.js",
    "react-dom": "https://cdn.jsdelivr.net/npm/react-dom@16.13.1/umd/react-dom.production.min.js",
    "vue": "https://cdn.jsdelivr.net/npm/vue@2.6.12/dist/vue.min.js",
    "react-app": "/react-app/react-app.js",
    "vue-app": "/vue-app/vue-app.js"
  }
}
            

              
                Copy
              
            
          

Step 4: Serve the Application

Serve the `index.html` file using a simple HTTP server. You can use a tool like `http-server`:

            npm install -g http-server
http-server -c-1
            

              
                Copy
              
            
          

Navigate to `http://localhost:8080/react` to see the React micro-frontend and `http://localhost:8080/vue` to see the Vue.js micro-frontend.

Important Considerations:

• This example uses simple routing based on URL prefixes. For more complex routing scenarios, consider using a dedicated routing library like `single-spa-router`.
• In a production environment, you would typically serve the micro-frontends from a CDN or other static asset hosting service.
• This example uses import maps for dependency management. Consider using a build tool like Webpack or Parcel to bundle your micro-frontends for production.

Advanced Single-SPA Techniques

Once you have a basic single-SPA application set up, you can explore more advanced techniques to improve the scalability and maintainability of your architecture.

Sharing Code with Parcels

Parcels allow you to share reusable components and logic between micro-frontends. This can help reduce code duplication and improve consistency across your application.

To create a parcel, you can use the `singleSpa.mountRootParcel` function:

            import * as singleSpa from 'single-spa';
import React from 'react';
import ReactDOM from 'react-dom';

function MyParcel(props) {
  return (<div>Hello from Parcel!  {props.name}</div>);
}

const parcel = singleSpa.mountRootParcel(() => {
  return Promise.resolve({
    bootstrap: () => Promise.resolve(),
    mount: (props) => {
      ReactDOM.render(<MyParcel name={props.name} />, document.getElementById('parcel-container'));
      return Promise.resolve();
    },
    unmount: () => {
      ReactDOM.unmountComponentAtNode(document.getElementById('parcel-container'));
      return Promise.resolve();
    },
  });
});

// To mount the parcel:
parcel.mount({ name: 'Example' });
            

              
                Copy
              
            
          

Communication Between Micro-frontends

Micro-frontends often need to communicate with each other to share data or trigger actions. There are several ways to achieve this:

• Shared Global State: Use a global state management library like Redux or Vuex to share data between micro-frontends.
• Custom Events: Use custom DOM events to broadcast messages between micro-frontends.
• Direct Function Calls: Export functions from one micro-frontend and import them into another. This approach requires careful coordination to avoid dependencies and circular references.
• Message Broker: Implement a message broker pattern using a library like RabbitMQ or Kafka to decouple micro-frontends and enable asynchronous communication.

Authentication and Authorization

Implementing authentication and authorization in a micro-frontend architecture can be challenging. Here are some common approaches:

• Centralized Authentication: Use a central authentication service to handle user login and authentication. The authentication service can issue tokens that are used to authenticate requests to the micro-frontends.
• Shared Authentication Module: Create a shared authentication module that is used by all micro-frontends. This module can handle token management and user session.
• API Gateway: Use an API gateway to handle authentication and authorization for all requests to the micro-frontends. The API gateway can verify tokens and enforce access control policies.

Benefits of Micro-Frontend Architecture with Single-SPA

• Increased Team Autonomy: Independent teams can develop and deploy micro-frontends without impacting other teams. This fosters autonomy and faster development cycles.
• Improved Scalability: Micro-frontends can be scaled independently, allowing you to optimize resource allocation and handle increased traffic.
• Enhanced Maintainability: Smaller, independent units are easier to maintain and update compared to a large monolithic application.
• Technology Diversity: Teams can choose the best technology stack for their micro-frontend, allowing for greater flexibility and innovation.
• Reduced Risk: Independent deployment of micro-frontends reduces the risk of deploying changes and simplifies rollback procedures.
• Gradual Migration: You can gradually migrate a monolithic application to a micro-frontend architecture without requiring a complete rewrite.

Challenges of Micro-Frontend Architecture

While micro-frontends offer many benefits, they also introduce some challenges:

• Increased Complexity: Managing multiple micro-frontends can be more complex than managing a single monolithic application.
• Communication Overhead: Coordinating communication between micro-frontends can be challenging.
• Deployment Complexity: Deploying multiple micro-frontends can be more complex than deploying a single application.
• Consistency: Maintaining a consistent user experience across micro-frontends can be difficult.
• Duplication: Without careful planning, code and dependencies can be duplicated across micro-frontends.
• Operational Overhead: Setting up and managing the infrastructure for multiple micro-frontends can increase operational overhead.

Best Practices for Building Micro-Frontends with Single-SPA

To successfully implement a micro-frontend architecture with single-SPA, follow these best practices:

• Define Clear Boundaries: Clearly define the boundaries between micro-frontends to minimize dependencies and communication overhead.
• Establish a Shared Style Guide: Create a shared style guide to ensure a consistent user experience across micro-frontends.
• Automate Deployment: Automate the deployment process to simplify the deployment of micro-frontends.
• Monitor Performance: Monitor the performance of each micro-frontend to identify and resolve issues.
• Use a Centralized Logging System: Use a centralized logging system to aggregate logs from all micro-frontends and simplify troubleshooting.
• Implement Robust Error Handling: Implement robust error handling to prevent errors in one micro-frontend from affecting other micro-frontends.
• Document Your Architecture: Document your micro-frontend architecture to ensure that everyone on the team understands how it works.
• Choose the Right Communication Strategy: Select the appropriate communication strategy based on the needs of your application.
• Prioritize Performance: Optimize the performance of each micro-frontend to ensure a fast and responsive user experience.
• Consider Security: Implement security best practices to protect your micro-frontend architecture from vulnerabilities.
• Adopt a DevOps Culture: Foster a DevOps culture to promote collaboration between development and operations teams.

Use Cases for Single-SPA and Micro-Frontends

Single-SPA and micro-frontends are well-suited for a variety of use cases, including:

• Large, Complex Applications: Micro-frontends can help break down large, complex applications into smaller, more manageable units.
• Organizations with Multiple Teams: Micro-frontends can enable different teams to work independently on different parts of the application. For example, in a global e-commerce company, one team could focus on the product catalog (e.g., based in Germany), while another handles the shopping cart (e.g., based in India), and a third manages user accounts (e.g., based in the US).
• Migrating Legacy Applications: Micro-frontends can be used to gradually migrate legacy applications to a more modern architecture.
• Building Platform-as-a-Service (PaaS) Solutions: Micro-frontends can be used to build PaaS solutions that allow developers to create and deploy their own applications.
• Personalized User Experiences: Different micro-frontends can be used to deliver personalized user experiences based on user roles, preferences, or location. Imagine a news website that dynamically loads different content modules based on the user's interests and reading history.

The Future of Micro-Frontends

The micro-frontend architecture is continuing to evolve, with new tools and techniques emerging to address the challenges of building and managing distributed frontend applications. Some key trends to watch include:

• Web Components: Web components are a standard for creating reusable UI elements that can be used in any web application. Web components can be used to build micro-frontends that are framework-agnostic and easily integrated into different applications.
• Module Federation: Module federation is a Webpack feature that allows you to share code and dependencies between different Webpack builds. Module federation can be used to build micro-frontends that are loosely coupled and independently deployable.
• Server-Side Rendering (SSR): Server-side rendering can improve the performance and SEO of micro-frontend applications. SSR can be used to render the initial HTML of the micro-frontend on the server, reducing the amount of JavaScript that needs to be downloaded and executed on the client.
• Edge Computing: Edge computing can be used to deploy micro-frontends closer to the user, reducing latency and improving performance. Edge computing can also enable new use cases for micro-frontends, such as offline access and real-time data processing.

Conclusion

Single-SPA is a powerful framework for building scalable, maintainable, and flexible micro-frontend architectures. By embracing the principles of micro-frontends and leveraging the capabilities of single-SPA, organizations can empower their teams, accelerate development cycles, and deliver exceptional user experiences. While micro-frontends introduce complexities, adopting best practices, carefully planning, and choosing the right tools are essential for success. As the micro-frontend landscape continues to evolve, staying informed about new technologies and techniques will be crucial for building modern and resilient web applications.