Builder

The @angular-architects/native-federation:build target — what it puts in angular.json, how it wraps Angular's ApplicationBuilder, and every option it accepts.

The @angular-architects/native-federation:build target is a thin wrapper around @angular/build:application. It runs the Native Federation build (shared bundles, exposed modules, remoteEntry.json), then delegates to Angular's Application Builder for the host/remote app itself. The same builder is used for both build and serve; the difference is configured by options.

On this page

• The angular.json layout
• What the builder does
• Builder options
• tsConfig and module resolution
• Native import maps
• Subresource Integrity
• Dev server & hot reload
• Developing npm-linked shared libraries
• Nx and @angular/build preloading
• Locale-aware output paths

The angular.json Layout

The init schematic doesn't replace your existing build — it shifts everything sideways and slots the federation builder on top. After running it, every federated project has four targets:

{
  "architect": {
    "build":           { "builder": "@angular-architects/native-federation:build", ... },
    "serve":           { "builder": "@angular-architects/native-federation:build", ... },
    "esbuild":         { "builder": "@angular/build:application", ... },        // ← old build
    "serve-original":  { "builder": "@angular/build:dev-server", ... }          // ← old serve
  }
}

• esbuild — the original @angular/build:application target (renamed from build). The federation builder calls into it.
• serve-original — the original @angular/build:dev-server target. The federation builder uses its options when serving.
• build — the new federation build. Its configurations point at <project>:esbuild:production / <project>:esbuild:development.
• serve — the new federation dev-server target. Points at <project>:serve-original:development.

The schematic's defaults look like this:

"build": {
  "builder": "@angular-architects/native-federation:build",
  "options": {
    "projectName": "mfe1",
    "tsConfig": "projects/mfe1/tsconfig.federation.json",
    "cacheExternalArtifacts": true,
    "entryPoints": ["projects/mfe1/src/main.ts"]
  },
  "configurations": {
    "production":  { "target": "mfe1:esbuild:production" },
    "development": { "target": "mfe1:esbuild:development", "dev": true }
  },
  "defaultConfiguration": "production"
},
"serve": {
  "builder": "@angular-architects/native-federation:build",
  "options": {
    "projectName": "mfe1",
    "tsConfig": "projects/mfe1/tsconfig.federation.json",
    "target": "mfe1:serve-original:development",
    "rebuildDelay": 500,
    "cacheExternalArtifacts": true,
    "dev": true,
    "devServer": true,
    "port": 0,
    "entryPoints": ["projects/mfe1/src/main.ts"]
  }
}

What the Builder Does

For every ng build or ng serve the federation builder runs roughly the following sequence:

1. Resolve the underlying target (the esbuild or serve-original target referenced by options.target) and load its options.
2. Construct an NFBuildAdapter over esbuild and Angular's SourceFileCache (see below).
3. Call the core's normalizeFederationOptions with the project's federation.config.mjs (falling back to federation.config.js if no .mjs file exists, or the explicit federationConfigPath option if set) and tsconfig.federation.json.
4. Validate that there are no invalid .-imports in the externals (a current Vite limitation — see vitejs/vite#21036). Shared mappings are checked by the core itself, at the end of normalizeFederationOptions — on the set left after pruning and wildcard expansion, so paths that were never going to be published stay quiet.
5. Run the core's buildForFederation — this writes the shared bundles, exposed modules and remoteEntry.json into the configured output directory.
6. If I18N is configured, post-process the federation artifacts with localize-translate (one bundle copy per target locale).
7. Hand off to buildApplication (build) or serveWithVite (serve), passing the computed externals through to esbuild and registering federation middleware on the dev server.
8. In watch / dev mode: re-run steps 5–6 on every Angular rebuild, debounced by rebuildDelay.

The build is rejected entirely (no federation artifacts written) when the underlying Angular build fails. Federation rebuilds in dev mode are cancellable: a new file change aborts an in-flight federation rebuild via an AbortSignal instead of stacking up.

Builder Options

Every property below comes from src/builders/build/schema.json:

tsConfig and Module Resolution

The tsConfig option doesn't only select which files are compiled — it is passed through to esbuild's BuildOptions, so it also decides how bare specifiers resolve.

The reason is that Angular's compiler plugin only hooks onLoad, leaving esbuild to resolve specifiers itself. Without an explicit tsconfig, esbuild only honours baseUrl/paths from an auto-discovered file named exactly tsconfig.json — which misses tsconfig.app.json / tsconfig.lib.json layouts and breaks workspace imports with Could not resolve. Angular's own application builder passes the same normalized path.

Practically: the tsconfig you point tsConfig at must declare the workspace baseUrl and paths, or extends a config that does. The tsconfig.federation.json the schematic generates already extends the workspace root config, so generated projects need no change.

Native Import Maps

Since 22.0.3. By default the adapter runs es-module-shims in shim mode (esmsInitOptions: { shimMode: true }), which rewrites the app's script tags to type="module-shim". Modern browsers now support import maps natively, so you can opt out of shim mode and let the browser resolve the import map directly:

"options": {
  "esmsInitOptions": { "shimMode": false }
}

The build and runtime sides must agree. If you disable shim mode in the builder, disable it on the runtime too — pass shimMode: false to the orchestrator's useShimImportMap (or initFederation) in your main.ts:

initFederation('federation.manifest.json', {
  ...useShimImportMap({ shimMode: false }),
  // ...
});

Native import maps require a recent browser (Chrome/Edge 133+, Safari 18.4+, Firefox 150+); shim mode remains the default for broader compatibility. See Runtime for the runtime side.

Subresource Integrity

Since 22.0.1. When Angular's own subresourceIntegrity option is enabled, the CLI stamps integrity and crossorigin attributes onto the polyfills and main script tags. The federation builder now preserves those attributes when it rewrites the tags for federation — only the type attribute is changed. This keeps SRI hashes intact for environments that require them (e.g. PCI DSS compliance).

Dev Server & Hot Reload

When serving, the builder layers two things on top of Angular's Vite-based dev server:

• Federation file middleware. Every request that matches a file under the federation output dir (the shared bundles, the exposed modules, remoteEntry.json) is served straight from disk with permissive CORS headers. This is what lets a host fetch a remote on localhost:4201 from a shell on localhost:4200.
• Build notifications (SSE). When buildNotifications.enable is true (the default), the dev server exposes an event stream at /@angular-architects/native-federation:build-notifications. Hosts can subscribe and trigger a reload whenever a remote rebuilds. The stream emits completed, cancelled and error events. More on automatic shell reloading.

Developing npm-linked Shared Libraries

A common local-development setup is to build a shared library in its own repo with ng build --watch (ng-packagr) and pull it into the host with npm link.

Because Native Federation shares such a library as an external, it is excluded from Angular's own build — the change lands under node_modules, which Angular's build watcher skips. The federation builder covers that gap: it detects linked shared packages and re-bundles them on change, so no cache clear or dev-server restart is needed.

Requirements:

• The library is listed in the shared section of your federation.config.mjs (via shareAll, an explicit shared entry, or sharedMappings).
• Its package directory under node_modules is a symlink — linked with npm link or the equivalent, not installed from a registry.
• The library is rebuilt on change so the symlink target actually updates (ng build --watch for an Angular library).

# 1. In the shared library's repo — build to dist/ and keep watching
ng build --watch

# 2. Publish the built package to the local npm link registry
cd dist/my-lib && npm link

# 3. In the host repo — link the package into node_modules
npm link @my-scope/my-lib

# 4. Run the host as usual
ng serve

Editing a source file in the library now rebuilds its dist/, and the builder re-bundles the affected shared external and logs Done!. To also refresh the browser automatically, enable SSE-based reloading with initFederation(manifest, { sse: true }); otherwise refresh manually.

Under the hood the builder resolves the real path of each symlinked shared package and adds it to the federation file watcher. Linked packages live under node_modules, so they are watched by polling, and a short debounce coalesces ng-packagr's atomic multi-file writes into one rebuild. Only the affected shared externals are re-bundled; registry-installed dependencies keep the version-only cache fast path (see core caching).

Nx and @angular/build Preloading

The builder disables two Angular build features by setting environment variables before @angular/build loads:

• NG_BUILD_OPTIMIZE_CHUNKS=0 — Angular's chunk optimization pass (on by default in Angular 22 for production builds, from three lazy chunks upwards) re-bundles the esbuild output after Native Federation has computed its import map, so shared externals such as @angular/core are no longer resolved as singletons. At runtime that surfaces as ɵɵdefineComponent is not a function.
• NG_BUILD_PARALLEL_TS=0 — lets the compilation steps share one cache, which is considerably faster here.

@angular/build reads those variables once, when it is first loaded. Under the Angular CLI the builder is loaded first, so this works. Nx loads @angular/build before it resolves the builder (nx/src/adapter/compat.js requires @angular/build/private to stub a version assertion), so the variables arrive too late and both features stay on — see #107 / #114.

The builder detects this and re-applies both settings to the already-loaded @angular/build, logging:

INFO  @angular/build was already loaded when this builder started (Nx preloads it),
      so its build environment was stale; re-applied useParallelTs=false,
      optimizeChunksThreshold=Infinity.

That line is informational — the problem was corrected and no action is needed. Two things are worth knowing:

• Nx replays cached artifacts, so run one uncached build (nx build my-app --skip-nx-cache) if a previous build produced broken output.
• To set the variables yourself instead, put them in a workspace-root .env file — Nx loads dotenv files before @angular/build — and add { "env": "NG_BUILD_OPTIMIZE_CHUNKS" } to the target's inputs so the cache reacts to changes. Setting NF_NG_BUILD_ENV_REPLAY=0 then keeps the builder from touching the loaded module at all.

If the builder instead warns that it could not re-apply a setting, @angular/build has changed internally: use the .env approach and report it upstream.

Locale-aware Output Paths

When the underlying Angular target has localize enabled (or an array of locales) the federation artifacts are written under the source-locale subfolder, mirroring Angular's convention:

dist/mfe1/browser/
├── en/                    ← source locale, original federation artifacts
│   ├── remoteEntry.json
│   ├── _angular_core.<hash>.js
│   └── ...
├── de/                    ← translated copy, generated by localize-translate
│   ├── remoteEntry.json
│   └── ...
└── fr/
    └── ...

Configure your production federation.manifest.json to point at the locale-specific URL (/de/remoteEntry.json). See I18N for the details.

How the Adapter Wraps esbuild

For builds that emit federation artifacts (shared externals, exposed modules, mapped paths) the adapter creates two distinct esbuild contexts:

• Mappings & exposed modules are bundled with Angular's full toolchain (the AOT compiler plugin, stylesheet handling, …) so an exposed component compiles exactly like it would in your app.
• Shared externals from node_modules are bundled with a plainer esbuild context — they're already-compiled JS and don't need the Angular plugins.

Both contexts share the same SourceFileCache Angular uses for incremental rebuilds, so a TypeScript file invalidated in the federation build is also picked up by the next Angular rebuild.

Related

• Schematics — the schematic that wires this angular.json for you.
• Custom Builder — drop in extra esbuild plugins via runBuilder.
• Core: Build Process — the underlying lifecycle the builder is wrapping.
• Core: Caching — what cacheExternalArtifacts caches and how invalidation works.