gem-hunter

vite-plugin-federation

Table of Contents

What is Module Federation?

Why this plugin

GA Support Scope

Compared to Other Vite Federation Plugins

Install

pnpm add -D vite-plugin-federation
# or
npm install -D vite-plugin-federation
# or
yarn add -D vite-plugin-federation

Public API Contract

Quick Start

A remote

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import federation from 'vite-plugin-federation';

export default defineConfig({
  plugins: [
    react(),
    federation({
      name: 'catalog',
      filename: 'remoteEntry.js', // stable name for examples; default is remoteEntry-[hash]
      exposes: {
        './Button': './src/Button.tsx',
      },
      shared: {
        react: { singleton: true, requiredVersion: '^19.2.4' },
        'react/': { singleton: true, requiredVersion: '^19.2.4' },
      },
      // manifest defaults to true → emits mf-manifest.json + mf-stats.json + mf-debug.json
    }),
  ],
  build: {
    target: 'esnext',
    cssCodeSplit: true,
  },
});

A host

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import federation from 'vite-plugin-federation';

export default defineConfig({
  plugins: [
    react(),
    federation({
      name: 'shell',
      remotes: {
        // String value → manifest-first remote (recommended)
        catalog: 'https://cdn.example.com/catalog/mf-manifest.json',
      },
      shared: {
        react: { singleton: true, requiredVersion: '^19.2.4' },
      },
    }),
  ],
  build: { target: 'esnext' },
});

// app.tsx
import { lazy, Suspense } from 'react';
import { loadRemoteFromManifest } from 'vite-plugin-federation/runtime';

const CatalogButton = lazy(async () => {
  const mod = await loadRemoteFromManifest(
    'catalog/Button',
    'https://cdn.example.com/catalog/mf-manifest.json',
    { cacheTtl: 30_000, retries: 2, timeout: 4_000 },
  );
  return { default: mod.default ?? mod };
});

export function App() {
  return (
    <Suspense fallback={null}>
      <CatalogButton />
    </Suspense>
  );
}

import { loadRemote } from 'vite-plugin-federation/runtime';
const mod = await loadRemote('catalog/Button');

An SSR host

// vite.config.ts
import federation from 'vite-plugin-federation';

export default {
  plugins: [
    federation({
      name: 'ssr-shell',
      remotes: { catalog: 'https://cdn.example.com/catalog/mf-manifest.json' },
      target: 'node', // optional; auto-detected from `build.ssr`
    }),
  ],
};

// server.ts
import {
  createServerFederationInstance,
  fetchFederationManifest,
  loadRemoteFromManifest,
  collectFederationManifestPreloadLinks,
} from 'vite-plugin-federation/runtime';

createServerFederationInstance({ name: 'ssr-shell', remotes: [], shared: {} });

const manifestUrl = process.env.CATALOG_MANIFEST_URL!;
const manifest = await fetchFederationManifest(manifestUrl, { cacheTtl: 30_000 });

const mod = await loadRemoteFromManifest('catalog/Button', manifestUrl, {
  target: 'node',
});

// Stream <link rel="modulepreload"> / <link rel="stylesheet"> hints
const links = collectFederationManifestPreloadLinks(manifestUrl, manifest, './Button');

Plugin Options

Exposes

exposes: {
  './Button': './src/Button.tsx',
  './ManualCssButton': {
    import: './src/ManualCssButton.tsx',
    css: { inject: 'manual' }, // 'head' | 'manual' | 'none' | true | false
  },
}

Remotes

remotes: {
  // Recommended: manifest-first
  catalog: 'https://cdn.example.com/catalog/mf-manifest.json',

  // Object form for legacy / mixed setups
  legacy: {
    name: 'legacyRemote',
    entry: 'https://cdn.example.com/legacy/remoteEntry.js',
    type: 'module',
    entryGlobalName: 'legacyRemote',
    from: 'vite',     // 'vite' | 'webpack'
    format: 'esm',    // 'esm' | 'systemjs' | 'var'
    shareScope: 'default',
  },
}

Shared

shared: {
  react: {
    singleton: true,
    strictSingleton: true,
    requiredVersion: '^19.2.4',
    strictVersion: true,
    allowNodeModulesSuffixMatch: true, // pnpm/symlinked layouts
  },
  'react/': { // trailing slash → matches package subpaths
    singleton: true,
    requiredVersion: '^19.2.4',
    allowNodeModulesSuffixMatch: true,
  },
  // Host-only share — host must provide; remote must not bundle a fallback
  'design-system': { import: false, requiredVersion: '^2.0.0' },
}

Runtime API

import {
  // Instances
  createFederationInstance,
  createServerFederationInstance,
  createFederationRuntimeScope,

  // Manifest
  fetchFederationManifest,
  registerManifestRemote,
  registerManifestRemotes,
  loadRemoteFromManifest,
  refreshRemote,
  connectRuntimeRemoteHmr,

  // Loading
  loadRemote,
  loadShare,
  loadShareSync,

  // Preload & warmup
  warmFederationRemotes,
  preloadRemote,
  createFederationManifestPreloadPlan,
  collectFederationManifestPreloadLinks,

  // Security
  verifyFederationManifestAssets,

  // Observability
  getFederationDebugInfo,
  clearFederationRuntimeCaches,

  // Re-exports of @module-federation/runtime
  registerPlugins,
  registerRemotes,
  registerShared,
} from 'vite-plugin-federation/runtime';

Manifest Protocol

Dev Experience

federation({
  // ...
  dev: {
    remoteHmr: true, // opt in to host <-> remote HMR wiring
    devtools: true, // default; set false to disable the devtools endpoint/overlay
    disableLiveReload: true, // DTS worker default: avoid page reloads for type-only changes
    disableHotTypesReload: false,
    disableDynamicRemoteTypeHints: false,
  },
});

SSR

TypeScript / DTS

federation({
  // ...
  dts: {
    generateTypes: { abortOnError: true },
    consumeTypes: { typesOnBuild: true, abortOnError: true },
  },
});

Production Runtime

import { loadRemoteFromManifest } from 'vite-plugin-federation/runtime';

const mod = await loadRemoteFromManifest('catalog/Button', catalogManifestUrl, {
  target: 'web', // or 'node'
  cacheTtl: 30_000, // ms; 0 = always refetch
  staleWhileRevalidate: true, // serve cached, refresh in the background
  force: false, // bypass cache for this call
  fallbackUrls: [backupManifestUrl],
  retries: 2,
  retryDelay: 200, // ms, with jitter
  timeout: 4_000, // ms, per attempt
  circuitBreaker: { failureThreshold: 3, cooldownMs: 30_000 },
  integrity: { mode: 'prefer-integrity' }, // or true / { mode: 'integrity' | 'content-hash' | 'both' }
  fetch, // bring your own
  fetchInit: { credentials: 'include' },
  shareScope: 'default',
  hooks: {
    manifestFetch: (e) => log(e),
    remoteRegister: (e) => log(e),
    remoteLoad: (e) => log(e),
    remoteRefresh: (e) => log(e),
  },
});

Multi-Tenant Deployments

import { createFederationRuntimeScope } from 'vite-plugin-federation/runtime';

const tenant = createFederationRuntimeScope(tenantId);
await tenant.registerManifestRemote('shop', tenantManifestUrl, { shareScope: tenantId });
const Page = await tenant.loadRemoteFromManifest('shop/Page', tenantManifestUrl);

Preload & Performance

import {
  createFederationManifestPreloadPlan,
  fetchFederationManifest,
  warmFederationRemotes,
} from 'vite-plugin-federation/runtime';

// Warm a set of remotes at app boot. Set preload: false to register only.
await warmFederationRemotes({
  catalog: {
    manifestUrl: catalogManifestUrl,
    preload: { resourceCategory: 'sync' },
  },
  checkout: {
    manifestUrl: checkoutManifestUrl,
    preload: false,
  },
});

// Build a route-aware preload plan
const catalogManifest = await fetchFederationManifest(catalogManifestUrl, { cacheTtl: 30_000 });
const plan = createFederationManifestPreloadPlan(
  catalogManifestUrl,
  catalogManifest,
  { '/product/:id': './Button' },
  {
    asyncChunkPolicy: 'css', // 'none' | 'js' | 'css' | 'all'
  },
);
// plan.links → [{ rel: 'modulepreload', href }, { rel: 'stylesheet', href }, ...]

// Per-remote runtime metrics surface through getFederationDebugInfo()
//   .runtime.remoteLoadMetrics

Security

OriginJS Compatibility & Migration

import {
  __federation_method_setRemote,
  __federation_method_getRemote,
  __federation_method_ensure,
  __federation_method_unwrapDefault,
  __federation_method_wrapDefault,
} from 'virtual:__federation__';

federation({
  // ...
  compat: { originjs: false, virtualFederationShim: false },
});

Examples

pnpm install
pnpm examples:build          # React host/remote + SSR + DTS smoke path
pnpm examples:dev            # React host/remote dev loop
pnpm examples:dts:build
pnpm examples:ssr:build
pnpm build                   # package + all workspaces with build scripts
pnpm --filter vite-plugin-federation test:e2e:browser-matrix
pnpm --filter vite-plugin-federation test:e2e:compat
pnpm --filter vite-plugin-federation test:e2e:shared

Troubleshooting

import { getFederationDebugInfo } from 'vite-plugin-federation/runtime';
console.log(getFederationDebugInfo());
// → instance, registered remotes, manifest cache + fetch timeline,
//   integrity verification log, circuit breaker state, load metrics,
//   shared providers + sharedResolutionGraph

Repository Layout

Development

pnpm install
pnpm check          # lint + type-check + unit tests for everything
pnpm dev            # turbo dev for the package
pnpm build          # build the package
pnpm lint
pnpm test           # vitest, all workspaces
pnpm format

pnpm --filter vite-plugin-federation test:e2e                     # default + compat + shared + dts:dev
pnpm --filter vite-plugin-federation test:e2e:browser-matrix      # Chromium / Firefox / WebKit
pnpm --filter vite-plugin-federation test:e2e:multi-remote
pnpm --filter vite-plugin-federation test:e2e:shared
pnpm --filter vite-plugin-federation test:e2e:ssr
pnpm --filter vite-plugin-federation test:e2e:compat
pnpm --filter vite-plugin-federation test:e2e:dts:dev
pnpm test:vite-matrix:smoke

pnpm --filter example-react-remote preview
pnpm --filter example-react-ssr-host serve

Internal docs

Release Flow

pnpm changeset             # author a changeset
pnpm version-packages      # bump versions + update generated release files
pnpm release               # build the package and publish via Changesets

CI / CD

License