esbuild Adapter

The esbuild adapter — a framework-agnostic Native Federation adapter, used by the React reference example.

The @softarc/native-federation-esbuild package is a thin, framework-agnostic adapter that plugs the core builder into esbuild. It powers the React reference example and can be used with any stack where you drive your own build script — there is no CLI wrapper or framework coupling.

What's in the Box

Why an Adapter?

The core builder is intentionally bundler-agnostic — it orchestrates the federation build and delegates the actual bundling to an NFBuildAdapter. The esbuild adapter is that bridge for esbuild:

• Two bundling modes — source-code entries (your exposed modules) and node-modules entries (shared dependencies) are bundled with different esbuild configurations. Shared dependencies get process.env.NODE_ENV defined and a CommonJS plugin that turns a require() of another shared package into a real ESM import, so CommonJS libraries Just Work.
• File writes + cache integration — esbuild runs with write: false; the adapter writes outputs into outputPath and tracks every input file through the core's federation cache, so watch-mode rebuilds only touch what changed. The shared-package cache follows the adapter's options, so changing target, sourcemap or fileReplacements re-bundles shared packages by itself.
• Code splitting — the core's chunks setting maps onto esbuild's splitting, so shared dependencies and exposed modules are split into chunks that load on demand.
• Shared mappings stay shared — a relative import that reaches into a shared mapping (../../libs/ui/src/button rather than @my-org/ui) is rewritten onto the mapping's specifier, so the library isn't bundled a second time next to its federated copy. See Shared Mappings.
• Watch mode — wraps esbuild.context() with a debounced RebuildQueue, an AbortSignal-aware rebuild loop, and the core file watcher. Cancelled rebuilds are aborted cleanly rather than racing.
• Framework presets — the frameworks option bundles per-framework esbuild settings (file replacements, loaders, extra resolveExtensions, esbuild plugins) into one value. React needs none; REACT_SKIP_LIST keeps its server-only builds out of the browser share.

Install

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

On the host page, you also want the orchestrator runtime for import-map + remote loading:

npm i @softarc/native-federation-orchestrator

In this Section

• Getting Started — walk through the React reference example end-to-end: federation.config.js, build.mjs, host page and run commands.
• Builder — reference for runEsBuildBuilder and every field of EsBuildBuilderOptions, plus the lower-level createEsBuildAdapter.
• Adapter Configuration — EsBuildAdapterConfig: extra esbuild plugins, frameworks presets, fileReplacements and custom loader mappings.
• React & CommonJS Interop — the CommonJS plugin, how React is bundled, shareAll overrides, REACT_SKIP_LIST, and the Shadow-DOM custom-element pattern.

Prerequisites

• Node 18+ — the adapter is ESM-only and uses top-level await in typical build scripts.
• "type": "module" in your project's package.json — the adapter and its entry points are native ESM.
• @softarc/native-federation ~4.9.0 — a peer dependency, installed next to the adapter. The adapter calls buildForFederation / rebuildForFederation from it, and your federation.config.js imports withNativeFederation and shareAll from the same copy.
• esbuild ships as a dependency of the adapter, so it needs no separate install.