@softarc/native-federation-esbuild

The esbuild adapter for Native Federation: the mental model of Module Federation, implemented on browser standards (ES modules and import maps) for Micro Frontends and plugin-based architectures.

📖 Documentation

Note

This is v4. Upgrading? See the migration guide. On Angular? Use the Angular adapter instead.

Features

• Framework-agnostic — plugs the core builder into esbuild for React, Preact, Lit or plain TypeScript; no CLI wrapper or framework coupling.
• Framework presets — per-framework esbuild settings (file replacements, loaders, resolveExtensions, CommonJS interop) as plugins. A React preset ships built-in.
• CommonJS just works — when a preset asks for it, a CJS require() of another shared package becomes a real ESM import instead of a shim that throws in the browser; everything else uses esbuild's own interop.
• Watch mode — a debounced, cancellable rebuild queue that only re-bundles what changed.

Quick start

Install the adapter next to its peer dependency, core:

npm i -D @softarc/native-federation @softarc/native-federation-esbuild

Describe what the application shares and exposes in federation.config.mjs:

import { withNativeFederation, shareAll } from '@softarc/native-federation/config';
import { REACT_SKIP_LIST } from '@softarc/native-federation-esbuild/frameworks/react';

export default withNativeFederation({
  name: 'mfe1',
  exposes: { './component': './src/component.tsx' },
  shared: shareAll(
    { singleton: true, strictVersion: true, requiredVersion: 'auto' },
    { skipList: REACT_SKIP_LIST }
  ),
});

Then drive the build from a small script:

import { runEsBuildBuilder } from '@softarc/native-federation-esbuild';

const dev = process.argv.includes('--dev');

const federation = await runEsBuildBuilder('federation.config.mjs', {
  outputPath: 'dist',
  tsConfig: 'tsconfig.json',
  entryPoints: ['src/component.tsx'],
  dev,
  watch: dev,
});

if (!dev) await federation.close();

The resulting remoteEntry.json is loaded at runtime by the orchestrator. The Getting Started guide walks through a complete React remote and host page, and the playground has runnable examples.

Documentation

• Builder — runEsBuildBuilder, every EsBuildBuilderOptions field and the lower-level createEsBuildAdapter
• Adapter configuration — esbuild plugins, frameworks presets, fileReplacements and loader
• React & CommonJS interop — the React preset, the CJS plugin and the Shadow-DOM custom-element pattern
• Core configuration and sharing dependencies
• Mental model
• FAQ

Using an AI coding assistant? Point it at llms.txt.

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md.

Credits

Big thanks to Zack Jackson for originally coming up with Module Federation and its mental model, and to Florian Rappl and the Angular Architects team for their feedback and contributions. Find the current team behind native-federation on our documentation website.

License

MIT