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 — when a framework preset requests it (the default React preset does) — run through @chialab/esbuild-plugin-commonjs 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.
• 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, the CommonJS plugin). A React preset ships built-in and is applied by default; fileReplacements lets you swap problematic CJS entry points for their pre-bundled variants (e.g. React's cjs/ files).

Install

npm i -D esbuild @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 built-in React preset, the CJS plugin, the fileReplacements map it applies, shareAll overrides, 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.
• esbuild — you install it yourself; the adapter imports esbuild directly rather than bundling a copy.
• @softarc/native-federation ~4.1.0 — pulled in as a dependency; the adapter calls buildForFederation / rebuildForFederation from it. @chialab/esbuild-plugin-commonjs ships bundled too, so neither needs a separate install.