Micro-Frontends: The Honest Reality After Trying It | Akousa

shell-app/              (host application)
  - top nav, sidebar, routing shell
  - shared auth context
  - shared design system

analytics-remote/       (Team Alpha)
  - /analytics/*
  - charts, dashboards, data export

users-remote/           (Team Beta)
  - /users/*
  - user management, roles, permissions

billing-remote/         (Team Gamma)
  - /billing/*
  - invoices, subscriptions, payment methods

monitoring-remote/      (Team Delta)
  - /monitoring/*
  - real-time WebSocket views, alerting

platform-shell/
  - authentication
  - top navigation
  - product switcher
  - shared analytics SDK

product-a/             (30 engineers, real-time collab)
  - full React app
  - WebSocket-heavy
  - own design system extensions

product-b/             (20 engineers, forms/CRUD)
  - full React app
  - heavy form validation
  - wizard-style workflows

product-c/             (15 engineers, data visualization)
  - React + D3
  - canvas-heavy rendering
  - minimal shared UI beyond the shell

product-d/             (10 engineers, admin/settings)
  - simpler React app
  - mostly configuration screens

// shell-app/webpack.config.js
const { ModuleFederationPlugin } = require("webpack").container;
 
module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: "shell",
      remotes: {
        analytics: "analytics@https://cdn.example.com/analytics/remoteEntry.js",
        billing: "billing@https://cdn.example.com/billing/remoteEntry.js",
        users: "users@https://cdn.example.com/users/remoteEntry.js",
      },
      shared: {
        react: {
          singleton: true,
          requiredVersion: "^18.2.0",
          eager: true,
        },
        "react-dom": {
          singleton: true,
          requiredVersion: "^18.2.0",
          eager: true,
        },
        "react-router-dom": {
          singleton: true,
          requiredVersion: "^6.20.0",
        },
      },
    }),
  ],
};

// analytics-remote/webpack.config.js
const { ModuleFederationPlugin } = require("webpack").container;
 
module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: "analytics",
      filename: "remoteEntry.js",
      exposes: {
        "./App": "./src/App",
        "./DashboardWidget": "./src/components/DashboardWidget",
      },
      shared: {
        react: {
          singleton: true,
          requiredVersion: "^18.2.0",
        },
        "react-dom": {
          singleton: true,
          requiredVersion: "^18.2.0",
        },
        "react-router-dom": {
          singleton: true,
          requiredVersion: "^6.20.0",
        },
      },
    }),
  ],
};

tsx

// shell-app/src/remotes/AnalyticsApp.tsx
import React, { Suspense, lazy } from "react";
import { RemoteErrorBoundary } from "../components/RemoteErrorBoundary";
import { RemoteLoadingSkeleton } from "../components/RemoteLoadingSkeleton";
 
const AnalyticsApp = lazy(() => import("analytics/App"));
 
export function AnalyticsRemote() {
  return (
    <RemoteErrorBoundary fallback={<RemoteUnavailable name="Analytics" />}>
      <Suspense fallback={<RemoteLoadingSkeleton />}>
        <AnalyticsApp />
      </Suspense>
    </RemoteErrorBoundary>
  );
}

tsx

// shell-app/src/remotes/registry.ts
interface RemoteConfig {
  url: string;
  scope: string;
  module: string;
  version: string;
  integrity?: string;
}
 
interface RemoteRegistry {
  [remoteName: string]: RemoteConfig;
}
 
async function fetchRemoteRegistry(): Promise<RemoteRegistry> {
  const response = await fetch("/api/remote-registry", {
    headers: { "Cache-Control": "no-cache" },
  });
 
  if (!response.ok) {
    throw new Error(`Remote registry fetch failed: ${response.status}`);
  }
 
  return response.json();
}
 
// Dynamic remote loading -- this is where the fun begins
async function loadRemote(remoteName: string): Promise<any> {
  const registry = await fetchRemoteRegistry();
  const config = registry[remoteName];
 
  if (!config) {
    throw new Error(`Remote "${remoteName}" not found in registry`);
  }
 
  // Check if the remote's container is already loaded
  if (window[config.scope]) {
    return window[config.scope];
  }
 
  // Dynamically inject the script tag
  await new Promise<void>((resolve, reject) => {
    const script = document.createElement("script");
    script.src = config.url;
    script.type = "text/javascript";
    script.async = true;
 
    if (config.integrity) {
      script.integrity = config.integrity;
      script.crossOrigin = "anonymous";
    }
 
    script.onload = () => resolve();
    script.onerror = () => reject(new Error(`Failed to load remote: ${config.url}`));
 
    document.head.appendChild(script);
  });
 
  // Initialize the remote container
  const container = window[config.scope];
  await container.init(__webpack_share_scopes__.default);
 
  return container;
}
 
export async function loadRemoteModule(remoteName: string, modulePath: string): Promise<any> {
  const container = await loadRemote(remoteName);
  const factory = await container.get(modulePath);
  return factory();
}

// Remote A says:
shared: {
  react: { singleton: true, requiredVersion: '^18.2.0' }
}
 
// Remote B says:
shared: {
  react: { singleton: true, requiredVersion: '^18.3.0' }
}
 
// Shell provides React 18.2.0
// Remote B's requirement is satisfied by ^18.3.0 (>= 18.3.0 < 19.0.0)
// Shell's 18.2.0 does NOT satisfy ^18.3.0
// Module Federation will either:
//   a) Load a second copy of React (breaking singleton)
//   b) Throw an error at runtime
//   c) Use 18.2.0 anyway and hope for the best

shared: {
  'react': { singleton: true, requiredVersion: '^18.2.0' },
  'react-dom': { singleton: true, requiredVersion: '^18.2.0' },
  'react-router-dom': { singleton: true, requiredVersion: '^6.20.0' },
  '@tanstack/react-query': { singleton: true, requiredVersion: '^5.0.0' },
  'zustand': { singleton: true, requiredVersion: '^4.4.0' },
  '@company/design-system': { singleton: true, requiredVersion: '^3.0.0' },
  '@company/auth-sdk': { singleton: true, requiredVersion: '^2.1.0' },
  '@company/analytics-sdk': { singleton: true, requiredVersion: '^1.5.0' },
  'date-fns': { requiredVersion: '^2.30.0' },
  'lodash-es': { requiredVersion: '^4.17.0' },
  'axios': { requiredVersion: '^1.6.0' },
}

// tools/shared-deps.js
// Single source of truth for all shared dependency versions
const SHARED_DEPS = {
  react: { version: "18.2.0", singleton: true, eager: false },
  "react-dom": { version: "18.2.0", singleton: true, eager: false },
  "react-router-dom": { version: "6.22.0", singleton: true, eager: false },
  "@tanstack/react-query": { version: "5.17.0", singleton: true, eager: false },
  "@company/design-system": { version: "3.2.1", singleton: true, eager: false },
};
 
function generateSharedConfig(options = {}) {
  const { eager = false } = options;
  const shared = {};
 
  for (const [pkg, config] of Object.entries(SHARED_DEPS)) {
    shared[pkg] = {
      singleton: config.singleton,
      requiredVersion: config.version,
      eager: eager || config.eager,
    };
  }
 
  return shared;
}
 
module.exports = { SHARED_DEPS, generateSharedConfig };

// ci/check-shared-deps.js
const { SHARED_DEPS } = require("@company/shared-deps");
const pkg = require("../package.json");
 
const violations = [];
 
for (const [dep, config] of Object.entries(SHARED_DEPS)) {
  const installed = pkg.dependencies[dep] || pkg.devDependencies[dep];
  if (!installed) continue;
 
  const cleanInstalled = installed.replace(/[\^~]/, "");
  if (config.singleton && cleanInstalled !== config.version) {
    violations.push(`${dep}: installed ${cleanInstalled}, expected ${config.version}`);
  }
}
 
if (violations.length > 0) {
  console.error("Shared dependency violations:");
  violations.forEach((v) => console.error(`  - ${v}`));
  process.exit(1);
}

tsx

// Shell routing
function ShellApp() {
  return (
    <BrowserRouter>
      <ShellLayout>
        <Routes>
          <Route path="/analytics/*" element={<AnalyticsRemote />} />
          <Route path="/billing/*" element={<BillingRemote />} />
          <Route path="/users/*" element={<UsersRemote />} />
          <Route path="/" element={<Dashboard />} />
        </Routes>
      </ShellLayout>
    </BrowserRouter>
  );
}
 
// Analytics remote -- DO NOT create another BrowserRouter!
function AnalyticsApp() {
  // This remote must use relative routes within the shell's router context
  return (
    <Routes>
      <Route path="/" element={<AnalyticsDashboard />} />
      <Route path="/reports" element={<Reports />} />
      <Route path="/reports/:id" element={<ReportDetail />} />
      <Route path="/export" element={<DataExport />} />
    </Routes>
  );
}

tsx

function ShellApp() {
  const location = useLocation();
 
  return (
    <ShellLayout>
      <div style={{ display: location.pathname.startsWith("/analytics") ? "block" : "none" }}>
        <AnalyticsRemote />
      </div>
      <div style={{ display: location.pathname.startsWith("/billing") ? "block" : "none" }}>
        <BillingRemote />
      </div>
      <div style={{ display: location.pathname.startsWith("/users") ? "block" : "none" }}>
        <UsersRemote />
      </div>
    </ShellLayout>
  );
}

// analytics-remote/webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.module\.css$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              modules: {
                localIdentName: "analytics__[local]__[hash:base64:5]",
              },
            },
          },
        ],
      },
    ],
  },
};

tsx

// shell-app/src/remotes/ShadowRemote.tsx
import { useRef, useEffect, useState } from "react";
import { createRoot } from "react-dom/client";
 
interface ShadowRemoteProps {
  children: React.ReactNode;
}
 
export function ShadowRemote({ children }: ShadowRemoteProps) {
  const hostRef = useRef<HTMLDivElement>(null);
  const [shadowRoot, setShadowRoot] = useState<ShadowRoot | null>(null);
 
  useEffect(() => {
    if (hostRef.current && !shadowRoot) {
      const shadow = hostRef.current.attachShadow({ mode: "open" });
      setShadowRoot(shadow);
    }
  }, [shadowRoot]);
 
  useEffect(() => {
    if (shadowRoot) {
      const container = document.createElement("div");
      shadowRoot.appendChild(container);
      const root = createRoot(container);
      root.render(children);
 
      return () => {
        root.unmount();
        shadowRoot.removeChild(container);
      };
    }
  }, [shadowRoot, children]);
 
  return <div ref={hostRef} />;
}

tsx

// Shared event types -- published as a package
// @company/micro-frontend-events
 
export interface MFEvents {
  "user:profile-updated": { avatarUrl: string; displayName: string };
  "cart:item-added": { productId: string; quantity: number };
  "notifications:count-changed": { count: number };
  "theme:changed": { mode: "light" | "dark" };
}
 
export function emitMFEvent<K extends keyof MFEvents>(eventName: K, detail: MFEvents[K]) {
  window.dispatchEvent(new CustomEvent(`mf:${eventName}`, { detail }));
}
 
export function onMFEvent<K extends keyof MFEvents>(eventName: K, handler: (detail: MFEvents[K]) => void): () => void {
  const listener = (event: Event) => {
    handler((event as CustomEvent).detail);
  };
 
  window.addEventListener(`mf:${eventName}`, listener);
  return () => window.removeEventListener(`mf:${eventName}`, listener);
}
 
// React hook for convenience
export function useMFEvent<K extends keyof MFEvents>(eventName: K, handler: (detail: MFEvents[K]) => void) {
  useEffect(() => {
    return onMFEvent(eventName, handler);
  }, [eventName, handler]);
}

tsx

// @company/shared-store
 
import { useSyncExternalStore } from "react";
 
type Listener = () => void;
 
class SharedStore<T> {
  private state: T;
  private listeners = new Set<Listener>();
 
  constructor(initialState: T) {
    this.state = initialState;
  }
 
  getState = (): T => {
    return this.state;
  };
 
  setState = (updater: T | ((prev: T) => T)): void => {
    this.state = typeof updater === "function" ? (updater as (prev: T) => T)(this.state) : updater;
    this.listeners.forEach((listener) => listener());
  };
 
  subscribe = (listener: Listener): (() => void) => {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  };
}
 
// Global stores, exposed via the shell
export interface UserState {
  id: string;
  displayName: string;
  avatarUrl: string;
  permissions: string[];
}
 
export interface NotificationState {
  unreadCount: number;
  lastChecked: number;
}
 
export const userStore = new SharedStore<UserState | null>(null);
export const notificationStore = new SharedStore<NotificationState>({
  unreadCount: 0,
  lastChecked: Date.now(),
});
 
// React hooks
export function useSharedUser(): UserState | null {
  return useSyncExternalStore(userStore.subscribe, userStore.getState, userStore.getState);
}
 
export function useSharedNotifications(): NotificationState {
  return useSyncExternalStore(notificationStore.subscribe, notificationStore.getState, notificationStore.getState);
}

1. Load shell HTML                          [50ms]
2. Load main JS bundle (includes React)     [200ms]
3. Load route-specific chunk                [100ms]
4. Render                                   [50ms]
Total: ~400ms

1. Load shell HTML                          [50ms]
2. Load shell JS bundle                     [150ms]
3. Shell renders, determines which remote   [20ms]
4. Fetch remote registry                    [50ms]
5. Load remoteEntry.js for the target       [80ms]
6. Module Federation negotiates shared deps [30ms]
7. Load remote's route-specific chunk       [100ms]
8. Remote renders                           [50ms]
Total: ~530ms

tsx

// shell-app/src/remotes/preload.ts
const PRELOAD_MAP: Record<string, string> = {
  "/analytics": "analytics",
  "/billing": "billing",
  "/users": "users",
};
 
export function preloadRemoteOnHover(path: string) {
  const remoteName = Object.entries(PRELOAD_MAP).find(([prefix]) => path.startsWith(prefix))?.[1];
 
  if (!remoteName) return;
 
  // Preload the remoteEntry.js on hover
  const link = document.createElement("link");
  link.rel = "prefetch";
  link.href = getRemoteEntryUrl(remoteName);
  link.as = "script";
  document.head.appendChild(link);
}
 
// Usage in navigation
function NavLink({ to, children }: NavLinkProps) {
  return (
    <Link to={to} onMouseEnter={() => preloadRemoteOnHover(to)} onFocus={() => preloadRemoteOnHover(to)}>
      {children}
    </Link>
  );
}

json

{
  "timestamp": "2025-12-19T14:32:00Z",
  "shell": "2.1.0",
  "remotes": {
    "analytics": {
      "version": "1.45.2",
      "deployedAt": "2025-12-19T14:30:00Z",
      "entryUrl": "https://cdn.example.com/analytics/1.45.2/remoteEntry.js",
      "commitSha": "abc123"
    },
    "billing": {
      "version": "3.12.0",
      "deployedAt": "2025-12-18T09:15:00Z",
      "entryUrl": "https://cdn.example.com/billing/3.12.0/remoteEntry.js",
      "commitSha": "def456"
    }
  },
  "sharedDeps": {
    "react": "18.2.0",
    "react-dom": "18.2.0"
  }
}

tsx

// integration-tests/analytics-in-shell.test.tsx
import { test, expect } from "@playwright/test";
 
test.describe("Analytics remote in shell", () => {
  test("loads analytics dashboard", async ({ page }) => {
    await page.goto("/analytics");
 
    // Wait for the remote to load (this is the micro-frontend tax in tests)
    await page.waitForSelector('[data-testid="analytics-dashboard"]', {
      timeout: 10000, // remotes can be slow to load in CI
    });
 
    await expect(page.locator('[data-testid="analytics-dashboard"]')).toBeVisible();
  });
 
  test("navigation between remotes preserves shell state", async ({ page }) => {
    await page.goto("/analytics");
    await page.waitForSelector('[data-testid="analytics-dashboard"]');
 
    // Verify user info in shell header
    const userName = await page.textContent('[data-testid="shell-user-name"]');
 
    // Navigate to billing
    await page.click('[data-testid="nav-billing"]');
    await page.waitForSelector('[data-testid="billing-dashboard"]', {
      timeout: 10000,
    });
 
    // Verify user info is still correct
    await expect(page.locator('[data-testid="shell-user-name"]')).toHaveText(userName!);
  });
 
  test("error boundary catches remote load failure", async ({ page }) => {
    // Simulate remote being unavailable
    await page.route("**/analytics/remoteEntry.js", (route) => route.abort());
 
    await page.goto("/analytics");
 
    await expect(page.locator('[data-testid="remote-unavailable"]')).toBeVisible();
 
    // Shell should still be functional
    await expect(page.locator('[data-testid="shell-header"]')).toBeVisible();
  });
});

tsx

// contracts/analytics-contract.test.ts
import { test, expect } from "vitest";
 
test("analytics remote exports expected interface", async () => {
  // This would load the actual built remote in a test environment
  const analyticsModule = await import("analytics/App");
 
  // Verify the remote exports a valid React component
  expect(analyticsModule.default).toBeDefined();
  expect(typeof analyticsModule.default).toBe("function");
 
  // If the remote accepts props, verify the interface
  // This catches breaking changes before deployment
});

// rspack.config.js with Module Federation 2.0
const { ModuleFederationPlugin } = require("@module-federation/enhanced/rspack");
 
module.exports = {
  plugins: [
    new ModuleFederationPlugin({
      name: "shell",
      remotes: {
        analytics: "analytics@https://cdn.example.com/analytics/mf-manifest.json",
      },
      shared: {
        react: { singleton: true, requiredVersion: "^18.2.0" },
        "react-dom": { singleton: true, requiredVersion: "^18.2.0" },
      },
      // 2.0 features
      runtimePlugins: [
        require.resolve("./src/mf-plugins/version-check"),
        require.resolve("./src/mf-plugins/error-reporting"),
      ],
    }),
  ],
};

monorepo/
  packages/
    design-system/          (shared UI components)
    shared-utils/           (shared utilities)
    shared-types/           (TypeScript interfaces)
  apps/
    main-app/               (single deployable application)
      src/
        features/
          analytics/        (Team Alpha owns this)
            components/
            hooks/
            routes/
            index.ts        (public API -- only import from here)
          billing/          (Team Beta owns this)
            components/
            hooks/
            routes/
            index.ts
          users/            (Team Gamma owns this)
            components/
            hooks/
            routes/
            index.ts

// .eslintrc.js (using eslint-plugin-boundaries)
module.exports = {
  plugins: ["boundaries"],
  settings: {
    "boundaries/elements": [
      { type: "analytics", pattern: "features/analytics/*" },
      { type: "billing", pattern: "features/billing/*" },
      { type: "users", pattern: "features/users/*" },
      { type: "shared", pattern: "shared/*" },
    ],
  },
  rules: {
    "boundaries/element-types": [
      "error",
      {
        default: "disallow",
        rules: [
          // Features can only import from shared, not from each other
          { from: "analytics", allow: ["shared"] },
          { from: "billing", allow: ["shared"] },
          { from: "users", allow: ["shared"] },
        ],
      },
    ],
  },
};

Micro-Frontends: The Honest Reality After Trying It

What Micro-Frontends Actually Solve

Conway's Law Is Not a Suggestion

The First Implementation: A Cautionary Tale

The Second Implementation: When It Actually Worked

Module Federation: The Actual Mechanics

Basic Host Configuration

Basic Remote Configuration

Loading a Remote in the Host

What the Configuration Does Not Tell You

The Shared Dependencies Problem

The Singleton Trap

The Dependency Matrix From Hell

What Actually Helps

Routing: The Underestimated Problem

The Two-Router Problem

The Deep Linking Problem

CSS Isolation: Harder Than You Think

The Approaches

Shared State: The Event Bus You Did Not Want to Build

Cross-Remote Communication Patterns

Performance: The Numbers Nobody Talks About

Bundle Size Impact

Loading Waterfall

Core Web Vitals

Build and Deploy: The Hidden Complexity

The Versioning Problem

Testing the Composition

rspack and Module Federation 2.0

When It Works: A Pattern I Have Seen Succeed

When It Is Overkill: Most Teams

The Alternative: Monorepo With Proper Boundaries

When to Actually Consider This

The Uncomfortable Conclusion

Related Posts

Modern CSS in 2026: The Features That Changed How I Write Styles

How to Speed Up Your Website — 20 Proven Performance Tips for 2026