Builder

Reference for runEsBuildBuilder and EsBuildBuilderOptions — the Native Federation esbuild adapter's high-level entry point.

runEsBuildBuilder is the high-level entry point most projects use. It loads federation.config.js, registers the esbuild adapter with the core, runs the initial build, and — when watch is on — keeps a file watcher and rebuild queue running until you call close().

Signature

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

const federation = await runEsBuildBuilder(
  federationConfigPath: string,
  options: EsBuildBuilderOptions,
): Promise<EsBuildBuilder>;

Minimal Call

const federation = await runEsBuildBuilder('federation.config.js', {
  outputPath: 'dist',
  entryPoints: ['src/bootstrap.tsx'],
});
await federation.close();

Everything else has a sensible default. The only required field is outputPath — the adapter throws [esbuild-builder] outputPath is required if it is missing.

EsBuildBuilderOptions

Return Value — EsBuildBuilder

interface EsBuildBuilder {
  federationInfo: FederationInfo;
  externals: string[];
  options: NormalizedEsBuildBuilderOptions;
  close(): Promise<void>;
}

• federationInfo — the result of the last successful build (remote name, exposed modules, shared descriptors, ...). In watch mode this is a live getter — read it whenever you need a fresh snapshot.
• externals — the list of module names the core marked as shared/external, forwarded to esbuild's external.
• options — the normalized, fully-defaulted options that were actually used. Handy for logging.
• close() — tears everything down: cancels any pending rebuild, stops the watcher, disposes all esbuild contexts, and calls esbuild.stop(). Always call it before exit, even in non-watch mode, so esbuild's daemon shuts down cleanly.

Watch Mode

When watch: true, the adapter:

1. Creates an NF file watcher that observes every source file the initial build touched.
2. Queues a rebuild on change. Rebuilds are debounced by rebuildDelay and serialized through a RebuildQueue — a new change mid-build cancels the in-flight rebuild via AbortSignal rather than racing it.
3. Calls rebuildForFederation on the core, which only re-bundles the entry points whose inputs changed.

Rebuild outcomes:

• Success — logs Federation rebuild done. and updates federationInfo.
• Cancelled — a newer change came in while the previous rebuild was still running. Logged only in verbose mode.
• Error — logs Federation rebuild failed!. The watcher keeps running; fix the file and the next save triggers another rebuild.

Lower-Level API — createEsBuildAdapter

If you drive buildForFederation / rebuildForFederation yourself (e.g. integrating with a custom dev server or another build tool's lifecycle), skip runEsBuildBuilder and construct just the adapter:

import { createEsBuildAdapter } from '@softarc/native-federation-esbuild';
import { setBuildAdapter, buildForFederation } from '@softarc/native-federation';

const adapter = createEsBuildAdapter({ plugins: [] });
setBuildAdapter(adapter);

await buildForFederation(config, normalizedOptions, externals);
await adapter.dispose();

createEsBuildAdapter returns an NFBuildAdapter with three methods:

• setup(name, options) — creates an esbuild context for a single bundle entry. Picks the source-code bundler or the node-modules bundler based on options.isMappingOrExposed.
• build(name, { modifiedFiles?, signal? }) — rebuilds, writes output files, and returns an NFBuildAdapterResult[] with file names. Aborts cleanly when signal fires.
• dispose(name?) — disposes a single context by name, or all contexts (plus esbuild.stop()) when called without arguments.