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
• Native import maps
• Subresource Integrity
• Dev server & hot reload
• 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 shared mappings or externals (a current Vite limitation — see vitejs/vite#21036).
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:

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('/assets/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.

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.