JSPM

nextjs-microfrontends

0.1.2
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
    • 0
  • Score
    100M100P100Q44932F
  • License MIT

Self-hosted microfrontends routing for Next.js — Vercel-independent multi-zone support with dev proxy, middleware, and zone-aware navigation

Package Exports

  • nextjs-microfrontends
  • nextjs-microfrontends/config
  • nextjs-microfrontends/next/client
  • nextjs-microfrontends/next/config
  • nextjs-microfrontends/next/dev-toolbar
  • nextjs-microfrontends/next/middleware

Readme

nextjs-microfrontends

A zero-config micro-frontends toolkit for Next.js 14+ (App Router).

Compose multiple independent Next.js applications behind a single domain using the multi-zone pattern — with automatic routing, middleware, asset isolation, and a local dev proxy.

Features

  • Declarative config — Define apps, routing, and environments in a single mfe.config.json.
  • Gateway rewrites — The default app automatically proxies routes to child apps.
  • Edge middleware — Route requests at the edge; works with Vercel, Cloudflare, and self-hosted.
  • Static asset isolation — Each child app gets a unique assetPrefix to avoid collisions.
  • Local dev proxy — Run all apps locally and access them through one localhost port.
  • Dev toolbar — Floating overlay showing which zone is active and live status of all apps.
  • Cross-zone navigation — React hook & Link component for seamless navigation across zones.
  • Edge-safe config resolver — No fs dependency; works in Edge Runtime and middleware.
  • CLI — microfrontends port and microfrontends proxy commands for local development.

Install

npm install nextjs-microfrontends
# or
pnpm add nextjs-microfrontends
# or
yarn add nextjs-microfrontends

Quick Start

1. Create a config file

// mfe.config.json
{
  "applications": {
    "gateway": {
      "default": true,
      "development": { "port": 3000 },
      "production": { "url": "https://gateway.example.com" }
    },
    "dashboard": {
      "routing": [{ "paths": ["/dashboard", "/dashboard/:path*"] }],
      "development": { "port": 3001 },
      "production": { "url": "https://dashboard.example.com" }
    },
    "admin": {
      "routing": [{ "paths": ["/admin", "/admin/:path*"] }],
      "development": { "port": 3002 },
      "production": { "url": "https://admin.example.com" }
    }
  }
}

2. Wrap your Next.js config

// next.config.ts (gateway app)
import { withMicrofrontends } from 'nextjs-microfrontends/next/config';

const nextConfig = {};

export default withMicrofrontends(nextConfig, { appName: 'gateway' });
// next.config.ts (child app)
import { withMicrofrontends } from 'nextjs-microfrontends/next/config';

const nextConfig = {};

export default withMicrofrontends(nextConfig, { appName: 'dashboard' });

3. Add middleware (gateway only)

// middleware.ts
import {
  createMicrofrontendsMiddleware,
  getMicrofrontendsMatcher
} from 'nextjs-microfrontends/next/middleware';

export const middleware = createMicrofrontendsMiddleware();

export const config = {
  matcher: getMicrofrontendsMatcher()
};

4. Run the dev proxy

npx microfrontends proxy --port 8000 --config ./mfe.config.json

All apps are now accessible at http://localhost:8000.

Config Reference

mfe.config.json

{
  "applications": {
    "<app-name>": {
      "default": true, // Exactly one app must be default (gateway)
      "routing": [
        // Child apps only
        { "paths": ["/path", "/path/:param*"] }
      ],
      "development": {
        "port": 3000, // Local dev port
        "fallback": "http://..." // Fallback URL if port is unreachable
      },
      "production": {
        "url": "https://..." // Production URL
      },
      "environments": {
        // Per-environment overrides
        "staging": { "url": "https://staging...." },
        "dev": { "url": "https://dev...." }
      }
    }
  }
}

Environment Variables

Variable Description
MFE_<APP_NAME>_URL Override resolved URL for an app (highest priority)
<APP_NAME>_PROXY_URL Legacy proxy URL override
MFE_CURRENT_APPLICATION Current app name (auto-set by withMicrofrontends)
MFE_CONFIG Serialized resolved config (auto-set)
ENV Environment name for environments[ENV] lookup
MFE_DEBUG Enable debug logging (true / 1)

Subpath Exports

Import path Description
nextjs-microfrontends Core types and config utilities
nextjs-microfrontends/config Config parser, resolver, matcher
nextjs-microfrontends/next/config withMicrofrontends() Next.js config wrapper
nextjs-microfrontends/next/middleware Edge middleware for gateway routing
nextjs-microfrontends/next/client React hooks (useMicrofrontends, useCrossZoneNavigation) and MicrofrontendsLink
nextjs-microfrontends/next/dev-toolbar Floating dev toolbar component

Cross-Zone Navigation

import { MicrofrontendsLink } from 'nextjs-microfrontends/next/client';

export function Nav() {
  return (
    <nav>
      <MicrofrontendsLink href="/dashboard">Dashboard</MicrofrontendsLink>
      <MicrofrontendsLink href="/admin">Admin</MicrofrontendsLink>
    </nav>
  );
}

The link component automatically detects cross-zone navigation and performs a full page navigation (via window.location) when the target is in a different zone.

Dev Toolbar

import { MfeDevToolbar } from 'nextjs-microfrontends/next/dev-toolbar';

// Add to your root layout (only renders in development)
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <MfeDevToolbar />
      </body>
    </html>
  );
}

CLI

# Show available ports for each app
npx microfrontends port

# Start the local dev proxy
npx microfrontends proxy --port 8000

# Use a custom config file
npx microfrontends proxy --port 8000 --config ./custom-config.json

# Show help
npx microfrontends --help

License

MIT