Skip to content

Angular MFE project setup with Native Federation

You will create the two applications used throughout this section, the OrdersPortal shell (orders-portal, port 4200) and the orders remote (orders-mfe, port 4201), both standalone Angular 22 applications, and turn them into a Native Federation host and remote. At the end, both build, and the remote’s build output contains a remoteEntry.json that the shell can load.

This page covers workspace creation only. What goes inside the remote and the shell is on Remote configuration and Host application setup.

The toolchain from Prerequisites: a supported Node.js, Angular CLI 22, and network access to the npm registry. Every command below was run with Angular CLI 22.2.7, Node.js 22.23 and @angular-architects/native-federation 22.2.5 on 2026-11-13.

Federation does not care where the source lives; it only needs each application’s build output at a URL. The repository layout is an organizational choice:

Layout How it works Strengths Costs
One workspace, several projects ng new with --create-application=false, then ng generate application per app One install, easy refactors, one place to align versions Teams share a repository; you must scope CI per project to keep deploys independent
One repository per application Each team runs its own ng new Clear ownership and permissions; truly independent pipelines Version alignment needs tooling (Renovate, a shared preset); harder cross-app changes

A common compromise is a monorepo while the platform is young, splitting repositories once team boundaries are stable. Whatever you choose, keep the deployment unit per application: each app has its own pipeline and its own URL.

This tutorial uses one workspace so you can follow along on one machine. The commands for separate repositories are the same, run in separate folders.

Step 2: Create the workspace and the two applications

Section titled “Step 2: Create the workspace and the two applications”

Create an empty workspace, then add both applications:

Terminal window
npx @angular/cli@22 new orders-workspace --create-application=false --skip-git
cd orders-workspace
npx ng generate application orders-portal --routing --style=css --ssr=false
npx ng generate application orders-mfe --routing --style=css --ssr=false

ng new in Angular 22 generates standalone applications by default (--standalone defaults to true), uses the esbuild-based @angular/build:application builder, sets up Vitest as the unit test runner, and creates zoneless applications. Each generated application has:

  • src/main.ts calling bootstrapApplication(App, appConfig).
  • src/app/app.config.ts with provideBrowserGlobalErrorListeners() and provideRouter(routes).
  • src/app/app.routes.ts exporting an empty Routes array.
  • src/app/app.ts, the root component (Angular 22’s default file naming drops the .component suffix).

There is no AppModule. If you are migrating an older NgModule-based application, see the legacy note at the end of this page.

Verify: npx ng build orders-portal and npx ng build orders-mfe both finish with “Application bundle generation complete.”

Install the adapter once at the workspace root:

Terminal window
npm install -D @angular-architects/native-federation@22.2.5

In separate repositories, run this in each repository.

Verify: npm ls @angular-architects/native-federation prints @angular-architects/native-federation@22.2.5. (ng version does not list the federation package.)

The package’s init schematic (also available as ng add) takes four options: --project, --port, --type (host, dynamic-host or remote, default remote) and --webcomponent (bootstrap as a custom element instead of a normal application).

Terminal window
npx ng g @angular-architects/native-federation:init --project orders-mfe --port 4201 --type remote

The schematic reports exactly what it changed:

Switching project to the application builder using esbuild ...
CREATE projects/orders-mfe/tsconfig.federation.json
CREATE projects/orders-mfe/federation.config.mjs
CREATE projects/orders-mfe/src/bootstrap.ts
UPDATE angular.json
UPDATE projects/orders-mfe/src/main.ts
UPDATE package.json

What each file does:

  • federation.config.mjs declares the remote’s name, what it exposes, and which packages are shared. Note the .mjs extension in the current release; older articles show federation.config.js.
  • src/bootstrap.ts contains the original bootstrap code (bootstrapApplication(App, appConfig)).
  • src/main.ts now calls initFederation() first and then dynamically imports ./bootstrap, so shared dependencies are negotiated before Angular loads.
  • tsconfig.federation.json is the TypeScript config used by the federation build.
  • package.json gains es-module-shims and the @softarc/native-federation-orchestrator runtime.

Verify: grep -c "@angular/core" projects/orders-mfe/src/main.ts prints 0 (main.ts now only initializes federation), and projects/orders-mfe/src/bootstrap.ts contains bootstrapApplication(App, appConfig).

Step 5: Turn orders-portal into a dynamic host

Section titled “Step 5: Turn orders-portal into a dynamic host”

Use dynamic-host for the shell so remote URLs come from a JSON manifest at runtime rather than being compiled in:

Terminal window
npx ng g @angular-architects/native-federation:init --project orders-portal --port 4200 --type dynamic-host

In addition to the files above, a dynamic host gets public/federation.manifest.json. The schematic pre-fills it with every remote it finds in the workspace:

{
"orders-mfe": "http://localhost:4201/remoteEntry.json"
}

Its main.ts passes that file to initFederation('federation.manifest.json', ...). Because the manifest lives in public/, it is copied to the build output unchanged and can be replaced per environment at deploy time without rebuilding the shell.

Verify: cat projects/orders-portal/public/federation.manifest.json prints the orders-mfe entry above.

Step 6: Understand the new angular.json targets

Section titled “Step 6: Understand the new angular.json targets”

The schematic keeps the Angular CLI’s own builders and wraps them. For each project, angular.json now has:

  • esbuild: the original @angular/build:application configuration (with es-module-shims added to polyfills).
  • build: @angular-architects/native-federation:build, which runs federation steps and delegates to the esbuild target.
  • serve-original: the original @angular/build:dev-server, holding the port you passed (4201 for the remote).
  • serve: the federation builder in dev-server mode, delegating to serve-original.

So ng build and ng serve keep working as before; they just run through the federation builder.

Verify: node -e "const a=require('./angular.json');console.log(Object.keys(a.projects['orders-mfe'].architect))" prints [ 'build', 'serve', 'test', 'esbuild', 'serve-original' ].

Terminal window
npx ng build orders-mfe
ls dist/orders-mfe/browser

You should see, among the hashed chunks:

  • remoteEntry.json: the remote’s federation metadata (name, exposed modules, shared packages and the exact versions it was built with).
  • importmap.json: the import map for the shared packages this build bundled (for example "@angular/core": "_angular_core.<hash>.js"), not for the remote’s own exposed modules, which are listed in remoteEntry.json.
  • Separately bundled shared packages, such as _angular_core.<hash>.js and rxjs.<hash>.js.

The shell’s output additionally contains federation.manifest.json. If those files are present, federation is wired up correctly. The remote does not expose anything useful yet; Remote configuration changes that.

orders-workspace/
angular.json
package.json
projects/
orders-portal/
federation.config.mjs
public/federation.manifest.json
src/main.ts (initFederation, then import('./bootstrap'))
src/bootstrap.ts (bootstrapApplication)
src/app/app.config.ts, app.routes.ts, app.ts
orders-mfe/
federation.config.mjs
src/main.ts
src/bootstrap.ts
src/app/...

Add two npm scripts so each team runs only its own app:

{
"scripts": {
"start:shell": "ng serve orders-portal",
"start:orders": "ng serve orders-mfe"
}
}
  • The schematic asks “Project name (press enter for default project)”. You omitted --project. Pass it explicitly in scripts and CI.
  • ng serve reports “Port 4200 is already in use”. Another process (often a previous ng serve or a static server) holds the port. Stop it, or change the port in the serve-original target, and update federation.manifest.json to match.
  • ng add or init fails with a peer dependency error on @angular/build. The adapter minor does not match Angular’s; see Prerequisites.
  • Other schematics (for example a UI library’s ng add) fail after federation was added. Some schematics expect bootstrapping to happen directly in main.ts. Run them against bootstrap.ts manually, or temporarily restore the original main.ts while you run them.
  • ng test warns that the buildTarget uses the federation builder. Unit tests do not need federation. Point the test target at the plain build with "options": { "buildTarget": "orders-portal:esbuild:development" }; see Local testing.

Applications created before standalone became the default still bootstrap with platformBrowser().bootstrapModule(AppModule). The federation schematic works the same way: it moves that call into bootstrap.ts. Remotes from that era expose an NgModule and the shell loads it with loadChildren(() => ...then(m => m.OrdersModule)). This still runs, but treat it as legacy: migrate remotes to expose standalone Routes with the official ng generate @angular/core:standalone migration before you federate them, so the contract between teams is a plain routes array rather than a module with its own providers.

Configure what orders-mfe exposes in Remote configuration, then load it from the shell in Host application setup.