Practical micro frontends: How we orchestrated multiple frameworks with single-spa

If you’ve ever tried to implement micro frontends in production, you know the frustration. The promise is beautiful: independent teams, independent deployments, technology freedom, scaling nirvana.

The reality is often more complex: duplicate dependencies bloat bundle sizes, routing conflicts emerge between applications, and teams find themselves needing more coordination than expected for seemingly simple changes.

At Nutrient, we’ve learned that micro frontends can work well when implemented thoughtfully. Our production system — which manages multiple applications across different frameworks — is proof of that. In this post, you’ll learn what we discovered about making this architecture practical.

Common micro frontend challenges

While micro frontends promise independent teams, faster deployments, and technology flexibility, in practice, they introduce new complexities. From our experience, most teams run into four recurring problem areas.

Dependency multiplication issues

When multiple micro frontends are developed independently, it’s easy to accidentally bundle the same library multiple times. Each application may include its own version of React, Vue, or other shared dependencies, often with slight version differences:

// App 1: React 18.2.0 (bundled) — 1.2MB
// App 2: React 18.1.0 (bundled) — 1.2MB
// App 3: React 17.0.0 (bundled) — 1.1MB
// Result: 3.5MB of React code for "micro" frontends

This usually happens because each app is bundled independently, dependencies are imported directly instead of being shared, and teams aren’t aligned on library versions. The result is larger bundles, slower load times, and “micro” frontends that aren’t actually lean. Single-spa solves this with shared dependencies and import maps, ensuring libraries are loaded once across all applications.

The routing war zone

Routing conflicts quickly emerge when different applications try to control the URL. Vue Router and React Router can fight for control, hash-based vs. browser routing can collide, and deep linking can break when switching between apps.

These conflicts make navigation unpredictable and create maintenance headaches. With single-spa, each application is assigned a clear URL scope using route-based activation, so only the relevant app responds to a given path, preventing clashes and keeping user navigation smooth.

The shared state chaos

State management across multiple micro frontends is another common pain point. Authentication can be scattered, user contexts can diverge, and event communication patterns that work for two apps collapse at scale. Session handling effectively becomes a distributed systems problem.

Without a well-defined shared state strategy, teams spend more time debugging inconsistencies than building features. Our approach uses shared libraries for authentication, user context, and core services, giving a single source of truth while preserving application independence.

The development coordination tax

Finally, “micro” teams often face significant coordination overhead. Releases require careful synchronization, build pipelines become complex, local development is difficult to configure, and integration testing grows exponentially harder as the number of apps increases.

We address this with orchestrated workflows and startup scripts that allow developers to run all micro frontends locally with minimal setup. Combined with selective builds and hot reload across frameworks, teams can work independently without being slowed down by excessive coordination.

Our architecture approach with single-spa

Instead of accepting these problems as inevitable, we built an architecture that addresses many of these challenges. Our production system manages multiple independent applications with different technology stacks in a more coordinated way.

The foundation: Module federation patterns

The core insight is that micro frontends aren’t just about splitting code — they’re about creating a sustainable development ecosystem. Our approach centers on three key patterns.

Consistent development environment

// Development import map with localhost URLs.
const developmentImportMap = {
  "@site/shared-lib": "http://localhost:3001/shared-lib.js",
  "@site/app-a": "http://localhost:3002/app-a.js",
  "@site/app-b": "http://localhost:3003/app-b.js",
  "@site/legacy-app": "http://localhost:3010/legacy-app.js",
};

// Production uses versioned CDN URLs:
const productionImportMap = {
  "@site/shared-lib": "https://cdn.example.com/v1.2.3/shared-lib.js",
  "@site/app-a": "https://cdn.example.com/v1.2.3/app-a.js",
};

Hybrid loading strategy for the real world

function registerApp(appName, customProps = {}) {
  singleSpa.registerApplication({
    name: appName,
    app: () => import(`@site/${appName}`),
    activeWhen: routeMatchers[appName],
    customProps,
  });
}

A practical shared dependency approach

// External dependencies prevent duplication.
const externals = [
  /^@site\/*/, // Site modules are external.
  "vue",
  "vue-router",
  "vuex", // Vue ecosystem.
  "react",
  "react-dom",
  "react-router-dom", // React ecosystem.
];

// Result:
// - Vue.js loaded once, shared by multiple applications.
// - React loaded once, shared by modern apps.
// - Significantly reduced bundle duplication.

Route-based activation that prevents chaos

In a micro frontend system, it’s critical that each application only responds to the URLs it owns. Without clear boundaries, multiple apps can compete for the same route, causing unpredictable behavior and broken navigation.

Using route-based activation, each micro frontend is assigned a specific URL prefix. Single-spa monitors the browser location and activates only the matching application, while all others remain inactive. This approach prevents conflicts, supports deep linking, and ensures smooth transitions between apps, even when mixing modern and legacy applications.

// Each application owns specific URL prefixes.
const routeMatchers = {
  "app-a": (location) => location.pathname.startsWith("/app-a"),
  "app-b": (location) => location.pathname.startsWith("/app-b"),
  "legacy-app": (location) => !isModernRoute(location.pathname),
};

With this setup, navigation is predictable, and each micro frontend can operate independently without interfering with others, providing a stable user experience across the platform.

Development workflow patterns

However, the architecture is only half the battle. The development workflow needs to minimize friction and maintain developer productivity.

Multi-application orchestration

Running multiple micro frontends locally can quickly become cumbersome without proper orchestration. To simplify this, we use a script that starts all registered applications in parallel while also allowing selective startup for specific apps:

# Single command starts all micro frontends
npm run start:all

# Selective development
IGNORE="app-x,app-y" npm run start:all

The command npm run start:all ensures that each application runs on a consistent port and reduces manual setup. When developers need to focus on a subset of applications, they can use the IGNORE variable to skip starting irrelevant apps. This approach abstracts away framework differences and provides a single, convenient entry point for running the full system locally.

Hot reload across frameworks

Maintaining fast feedback loops is essential when working across multiple frameworks. Modern framework development servers offer Hot Module Replacement (HMR), which updates changes instantly without a full page refresh.

In addition, shared libraries are configured to propagate updates automatically. This means that when a common module, such as authentication or theming, is modified, the changes are immediately reflected across all micro frontends without restarting servers. This setup reduces context switching, minimizes downtime during development, and enables multiple teams to work efficiently in parallel.

The shared common library pattern

To prevent code duplication and enforce consistency, all micro frontends import core services from a centralized shared library:

// Every micro frontend imports shared functionality.
import { auth, user, http, themes } from "@site/shared-lib";

// Core shared services prevent code duplication:
export const auth = authService; // Authentication management
export const user = userService; // User context
export const http = httpService; // API client
export const themes = themeService; // Consistent theming

This shared library contains essential services such as authentication, user context, API clients, and theming. By using these centralized modules, each application maintains consistent behavior, reduces bundle size, and avoids duplicating code. This pattern also enables incremental adoption, allowing legacy applications to gradually integrate shared functionality without a full rewrite.

Production patterns and performance

Building micro frontends for production involves more than just writing code — it requires a structured approach to bundling, dependency management, and deployment. Unlike a monolith where a single build produces one output, each micro frontend must be packaged independently, while ensuring shared libraries aren’t duplicated and versions remain consistent. Effective orchestration of the build process is essential to maintain predictable performance, minimize bundle sizes, and streamline deployment across multiple teams.

This leads naturally to the next step: orchestrating production builds in a way that coordinates all applications while maintaining their independence.

Production build orchestration

Building multiple micro frontends for production requires coordinating each application’s bundling, mapping, and versioning. We encapsulate this process in a single asynchronous function:

async function buildProduction() {
  await buildAllApplications();
  await generateImportMaps();
  await applyVersioning();
}

The buildAllApplications() function bundles each micro frontend individually with framework-specific optimizations, ensuring that each app is production-ready. Afterward, generateImportMaps() produces a JSON map that tells the browser where to load each micro frontend and its shared libraries. Finally, applyVersioning() guarantees that deployed applications reference exact versions of libraries, which avoids cache-related bugs and ensures reliable deployments.

Performance optimization results

After implementing this architecture, the performance improvements are evident. Previously, a monolithic application would load a single, very large bundle, resulting in slow initial load times, long build processes, and rigid deployment cycles. Team coordination was also a bottleneck, as releasing a small change required redeploying the entire application.

With our micro frontend approach, shared dependencies are loaded once and applications are lazy-loaded as needed. This leads to smaller initial downloads, faster page loads, and the ability for teams to build and deploy individual apps independently. Feature rollouts can also be selective, reducing risk and improving deployment flexibility.

Each micro frontend can be containerized and deployed independently using standard Docker patterns.

Migration strategy: From monolith to micro

The key to adopting micro frontends successfully is taking an incremental migration approach rather than attempting a full rewrite.

The graduated migration approach

Phase 1: Extract shell and shared dependencies

Start with single-spa root configuration and common library extraction. Keep the existing monolith as a single application while establishing patterns:

// Initial setup — monolith remains as a single app.
singleSpa.registerApplication(
  "legacy-app",
  () => import("./legacy-app.js"),
  () => true, // Always active initially.
  {},
);

Phase 2: Incremental extraction

Extract high-value, low-risk features first:

• Authentication flows (clear boundaries)
• Configuration pages (minimal dependencies)
• New features (start micro from day one)
• Data visualization components (isolated)
• Document processing features (consider [Nutrient’s SDK solutions][] for consistent document handling)

Phase 3: Legacy integration

Handle the complex parts with bridge patterns:

// Route-based fallback to legacy application.
const routeMatchers = {
  "auth-app": (location) => location.pathname.startsWith("/auth"),
  "config-app": (location) => location.pathname.startsWith("/config"),
  legacy: (location) => !isExtractedRoute(location.pathname), // Everything else
};

Migration timeline

Below is a realistic enterprise migration approach:

• Phase 1 — Foundation setup and common library extraction
• Phase 2 — Extract simple, isolated features first
• Phase 3 — Gradual legacy integration with bridge patterns

Lessons learned and anti-patterns

Through production experience, we’ve learned what works and what doesn’t.

What works

• Start with shared dependencies — Get the common library architecture right first
• Route-based activation — URL patterns prevent application conflicts elegantly
• Technology graduation — SystemJS → ES modules as applications mature
• Development port consistency — Consistent port ranges prevent conflicts

What doesn’t work

• Shared state across boundaries — Keep micro frontends truly independent
• Complex inter-app communication — Prefer URL-based communication over event buses
• Framework mixing within apps — One framework per micro frontend, period
• Perfect shared component libraries — Accept some duplication for true independence
• Over-engineering coordination — Simple patterns beat complex orchestration

Performance lessons learned

Managing shared dependencies is one of the trickiest aspects of micro frontend architecture. Attempting to share every library across applications might seem efficient, but in practice, it creates version conflicts, brittle builds, and long-term maintenance headaches. Instead, the key is to focus on sharing only the core frameworks and your own common modules. The following example illustrates which dependencies to avoid sharing broadly and which are safe to centralize for consistency and reduced duplication:

// DON'T: Try to share every possible dependency.
const problematicExternals = [
  "lodash",
  "moment",
  "axios",
  "ramda",
  "date-fns",
  // ... 200+ more dependencies
];

// DO: Share framework essentials only.
const effectiveExternals = [
  "vue",
  "react",
  "react-dom",
  "@site/*", // Your own modules
];

The sweet spot is sharing frameworks and your own modules while allowing applications to bundle their utility libraries. This prevents version conflicts while maintaining reasonable bundle sizes.

Team organization insights

• Ownership — Teams own related micro frontends
• Governance — Central team maintains shared patterns
• Quality gates — Automated cross-application testing

Advanced patterns

As your micro frontend ecosystem grows, runtime errors in one application can impact the entire platform. To maintain stability and a good user experience, it’s important to handle errors gracefully at both the application and orchestration level. Implementing robust error boundaries ensures failures are contained and reported without breaking unrelated parts of the system.

Error boundaries across applications

In React, error boundaries catch rendering errors in their child components, preventing crashes from propagating. At the single-spa orchestration level, you can also listen for lifecycle events like LOAD_ERROR to detect and log failures when micro frontends fail to load. Combining these approaches gives full-stack resilience, allowing individual micro frontends to fail safely, while keeping the overall platform operational:

// React error boundaries.
class MicroFrontendErrorBoundary extends React.Component {
  componentDidCatch(error, errorInfo) {
    window.CommonLib.logging.reportError(error, {
      ...errorInfo,
      microFrontend: this.props.appName,
    });
  }
}

// Single-spa error handling.
window.addEventListener("single-spa:routing-event", (evt) => {
  const { appsByNewStatus } = evt.detail;
  appsByNewStatus.LOAD_ERROR?.forEach((app) => {
    console.error(`Failed to load: ${app.name}`);
  });
});

After exploring advanced patterns, including error boundaries and resilient orchestration, you might be wondering how to apply these ideas in practice. To make the concepts concrete, the next section walks through building a simple single-spa micro frontend setup from scratch. This hands-on demo will illustrate route-based activation, independent deployments, and shared orchestration — the very principles discussed in this post — in a manageable, easy-to-follow project.

Getting started: Build your first single-spa application

This section will walk through creating a simple micro frontend setup to demonstrate the core concepts. You’ll build a root application that orchestrates two micro frontends.

Prerequisites

Before starting, ensure you have:

• Node.js 18+ installed
• Basic knowledge of JavaScript and modern frameworks
• A code editor

Step 1: Create the root application

mkdir micro-frontend-demo
cd micro-frontend-demo
mkdir root-app
cd root-app
npm init -y
npm install single-spa

Create index.html:

<!DOCTYPE html>
<html>
  <head>
    <title>Micro-Frontend Demo</title>
    <script src="https://cdn.jsdelivr.net/npm/systemjs@6.14.1/dist/system.min.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/systemjs@6.14.1/dist/extras/amd.min.js"></script>
  </head>
  <body>
    <div id="root"></div>
    <script type="systemjs-importmap">
      {
        "imports": {
          "single-spa": "https://cdn.jsdelivr.net/npm/single-spa@5.9.4/lib/system/single-spa.min.js",
          "@demo/root": "./root-config.js",
          "@demo/navbar": "http://localhost:3001/demo-navbar.js",
          "@demo/home": "http://localhost:3003/demo-home.js",
          "@demo/dashboard": "http://localhost:3002/demo-dashboard.js"
        }
      }
    </script>
    <script type="module">
      System.import("@demo/root");
    </script>
  </body>
</html>

Create root-config.js:

System.register(["single-spa"], function (_export, _context) {
  "use strict";

  var registerApplication, start;

  return {
    setters: [
      function (_singleSpa) {
        registerApplication = _singleSpa.registerApplication;
        start = _singleSpa.start;
      },
    ],
    execute: function () {
      // Register micro frontends.
      registerApplication({
        name: "@demo/navbar",
        app: () => System.import("@demo/navbar"),
        activeWhen: () => true, // Always active
      });

      registerApplication({
        name: "@demo/home",
        app: () => System.import("@demo/home"),
        activeWhen: (location) => location.pathname === "/",
      });

      registerApplication({
        name: "@demo/dashboard",
        app: () => System.import("@demo/dashboard"),
        activeWhen: (location) => location.pathname.startsWith("/dashboard"),
      });

      // Start Single-SPA
      start();
    },
  };
});

Step 2: Create a navigation bar micro frontend

cd ../
mkdir navbar-app
cd navbar-app
npm init -y
npm install webpack webpack-cli webpack-dev-server single-spa

Create webpack.config.js:

const path = require("path");

module.exports = {
  mode: "development",
  entry: "./src/demo-navbar.js",
  output: {
    filename: "demo-navbar.js",
    path: path.resolve(__dirname, "dist"),
    libraryTarget: "system",
  },
  devServer: {
    port: 3001,
    headers: {
      "Access-Control-Allow-Origin": "*",
    },
  },
  externals: ["single-spa"],
};

Create src/demo-navbar.js:

let domElement;

export function mount(props) {
  domElement = document.createElement("nav");
  domElement.innerHTML = `
    <style>
      nav { background: #333; padding: 1rem; }
      nav a { color: white; margin-right: 1rem; text-decoration: none; }
    </style>
    <a href="/">Home</a>
    <a href="/dashboard">Dashboard</a>
  `;
  document.body.prepend(domElement);
  return Promise.resolve();
}

export function unmount(props) {
  if (domElement) {
    domElement.remove();
  }
  return Promise.resolve();
}

Step 3: Create a home page micro-frontend

cd ../
mkdir home-app
cd home-app
npm init -y
npm install webpack webpack-cli webpack-dev-server single-spa

Create webpack.config.js:

const path = require("path");

module.exports = {
  mode: "development",
  entry: "./src/demo-home.js",
  output: {
    filename: "demo-home.js",
    path: path.resolve(__dirname, "dist"),
    libraryTarget: "system",
  },
  devServer: {
    port: 3003,
    headers: {
      "Access-Control-Allow-Origin": "*",
    },
  },
  externals: ["single-spa"],
};

Create src/demo-home.js:

let domElement;

export function mount(props) {
  domElement = document.createElement("main");
  domElement.innerHTML = `
    <style>
      main {
        padding: 2rem;
        max-width: 1200px;
        margin: 0 auto;
      }
      h1 {
        color: #333;
        font-size: 2.5rem;
        margin-bottom: 1rem;
      }
      p {
        color: #666;
        font-size: 1.1rem;
        line-height: 1.6;
        margin-bottom: 1rem;
      }
      .features {
        display: grid;
        grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
        gap: 1.5rem;
        margin-top: 2rem;
      }
      .feature-card {
        background: #f5f5f5;
        padding: 1.5rem;
        border-radius: 8px;
        border-left: 4px solid #333;
      }
      .feature-card h3 {
        margin-top: 0;
        color: #333;
      }
    </style>
    <h1>Welcome to Micro-Frontend Demo</h1>
    <p>This is a Single-SPA demonstration showcasing micro-frontend architecture patterns.</p>
    <p>Each section of this application is loaded independently and can be deployed separately.</p>

    <div class="features">
      <div class="feature-card">
        <h3>Independent Deployment</h3>
        <p>Each micro-frontend can be deployed independently without affecting others.</p>
      </div>
      <div class="feature-card">
        <h3>Framework Agnostic</h3>
        <p>Different micro-frontends can use different frameworks (React, Vue, Angular, etc.).</p>
      </div>
      <div class="feature-card">
        <h3>Route-based Activation</h3>
        <p>Micro-frontends are loaded and mounted based on the current route.</p>
      </div>
    </div>
  `;
  document.getElementById("root").appendChild(domElement);
  return Promise.resolve();
}

export function unmount(props) {
  if (domElement) {
    domElement.remove();
  }
  return Promise.resolve();
}

Step 4: Create a dashboard micro-frontend

cd ../
mkdir dashboard-app
cd dashboard-app
npm init -y
npm install webpack webpack-cli webpack-dev-server single-spa

Create webpack.config.js:

const path = require("path");

module.exports = {
  mode: "development",
  entry: "./src/demo-dashboard.js",
  output: {
    filename: "demo-dashboard.js",
    path: path.resolve(__dirname, "dist"),
    libraryTarget: "system",
  },
  devServer: {
    port: 3002,
    headers: {
      "Access-Control-Allow-Origin": "*",
    },
  },
  externals: ["single-spa"],
};

Create src/demo-dashboard.js:

let domElement;

export function mount(props) {
  domElement = document.createElement("main");
  domElement.innerHTML = `
    <h1>Dashboard</h1>
    <p>This is a micro frontend dashboard loaded at runtime.</p>
    <div id="dashboard-content">
      <h3>Features:</h3>
      <ul>
        <li>Independent deployment</li>
        <li>Framework isolation</li>
        <li>Shared routing</li>
      </ul>
    </div>
  `;
  document.getElementById("root").appendChild(domElement);
  return Promise.resolve();
}

export function unmount(props) {
  if (domElement) {
    domElement.remove();
  }
  return Promise.resolve();
}

Step 5: Run the demo

Open four terminals and run:

# Terminal 1 — Root app
cd root-app
npx serve . -p 3000 -s

# Terminal 2 - Navbar app
cd navbar-app
npx webpack serve

# Terminal 3 - Home app
cd home-app
npx webpack serve

# Terminal 4 - Dashboard app
cd dashboard-app
npx webpack serve

Visit http://localhost:3000 to see your micro frontend architecture in action.

What you’ve built

This demo illustrates key micro frontend patterns:

• Route-based activation: Home page loads on /, dashboard loads on /dashboard
• Independent deployment: Each micro-frontend runs on its own port (navbar:3001, dashboard:3002, home:3003)
• Shared orchestration: Root application manages the overall experience
• Runtime integration: Applications load and mount dynamically
• Always-active components: Navbar remains visible across all routes

Next steps

From here, you can:

• Replace the vanilla JavaScript with your preferred frameworks (React, Vue, Angular)
• Add shared dependencies through import maps
• Implement error boundaries and loading states
• Implement development utilities (e.g. shared startup script, logging)
• Add authentication and shared state management

Conclusion: When they make sense

Our production micro frontend architecture demonstrates that with thoughtful patterns, proper tooling, and realistic expectations, you can achieve:

• Increased team independence with some coordination tradeoffs
• Technology diversity balanced against complexity costs
• Incremental migration paths for legacy applications
• Improved developer experience in specific contexts
• More flexible deployment cycles for independent features

The key is solving real problems with pragmatic architectural patterns, not following architectural trends.

Use our approach if:

• You need to migrate legacy applications incrementally
• You value team autonomy and technology choice flexibility
• You’re building applications with clear domain boundaries

Stick with monoliths if:

• You have a small team (fewer than 10 developers)
• Your application has tight coupling between all features
• You prioritize simplicity over scalability
• Performance is more critical than development velocity

In the end, micro frontends aren’t a silver bullet — they’re a scaling tool. When applied thoughtfully, they let teams evolve independently, modernize incrementally, and manage complexity with structure rather than chaos. The patterns outlined here aren’t theoretical; they’re battle-tested solutions from real production systems. Whether you’re starting a migration or refining an existing setup, focus on solving tangible coordination and delivery problems first. That’s where micro frontends truly shine.