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 and waits for a running one, stops the watcher, and disposes all esbuild contexts. Calling it more than once is safe. Always call it before exit, even in non-watch mode, so the process can shut down cleanly.

Watch Mode

When watch: true, the adapter:

1. Creates an NF file watcher that observes every source file the initial build touched, plus the source directories of your shared mappings — so a file added to a mapped library after the last build is picked up too.
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. The changes of a cancelled or failed rebuild carry over into the next one.
3. Calls rebuildForFederation on the core, which only re-bundles the entry points whose inputs changed.

A shared package you are developing through npm link sits outside the watched sources. Set watchLinkedDeps: true to have the watcher poll its real directory as well. See Watching npm-linked shared dependencies.

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: [] }, { workspaceRoot: process.cwd() });
setBuildAdapter(adapter);

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

The first argument is the EsBuildAdapterConfig. The optional second argument takes workspaceRoot, the directory esbuild runs from; it defaults to the working directory. runEsBuildBuilder passes its own workspaceRoot here.

createEsBuildAdapter returns an NFBuildAdapter with three methods and an externalsCacheKey (see Shared Packages and the Cache):

• setup(name, options) — creates an esbuild context for a single bundle entry, replacing any existing context of that name. Shared packages (options.kind === 'shared') get the node-modules settings; exposed modules and shared mappings get the source-code settings.
• build(name, { modifiedFiles?, signal? }) — rebuilds, writes output files, and returns an NFBuildAdapterResult[] naming each file and the entry it was built from. Aborts cleanly when signal fires.
• dispose(name?) — disposes a single context by name, or all contexts when called without arguments.