Part 7 of an 8-part series on Native Federation v4 for enterprise architecture teams. New to the series? Start with Part 1: The Mental Model, Revisited.
The first six parts explained how Native Federation v3 and v4 work. This one is about getting from one to the other.
The good news is that you don't need a "big bang" release. You don't have to stop every team, upgrade everything and ship it all on one night. Because v3 and v4 share the same remoteEntry.json format, you can move one app at a time, and the page keeps working the whole way through.
This article is based on the latest stable releases: Orchestrator 4.10.1, core 4.10.1 and Angular adapter 22.2.5. As in Parts 4 to 6, the import map below is real output from running the Orchestrator's own code.
v3 vs. v4 at a glance
| Topic | v3 | v4 | Explained in |
|---|---|---|---|
| Where the code lives | One repository, angular-architects/module-federation-plugin | Separate repositories under the native-federation organization | Part 2 |
| Angular versions | 14 to 21 | 20 and newer | This article |
| Config file | federation.config.js, CommonJS (require) | federation.config.mjs, ES modules (import) | Part 3 |
| Browser runtime | Classic Runtime | Orchestrator (Classic Runtime is end-of-life) | Part 4, Part 5 |
| Sharing a library | Only on an exact version match | Across a version range | Part 4, Part 5 |
singleton, strictVersion, requiredVersion | Written by the build, ignored by the runtime | Used to pick versions | Part 5 |
| Share scopes, pooling, strict mode | Not available | Available | Part 6 |
| Caching between page loads | None | In memory by default, optional browser storage | Part 5 |
| Loading a remote in code | Global loadRemoteModule | Returned by initFederation() (the global one is deprecated) | This article |
For the full list, see the official v3 vs v4 page.
Why the host moves first
The key to a calm migration is the contract from Part 2: the host and its remotes only talk through remoteEntry.json. The Orchestrator reads files written by v3 builds as well as v4 builds (Orchestrator docs).
So the order is simple: move the host first, then the remotes, one at a time. The host is the one place where the runtime runs, so upgrading it gives every remote the benefits of v4 straight away, even remotes nobody has touched yet.
I tested this middle state with Orchestrator 4.10.1. The host is a v4 build on Angular 20.1.4. mfe1 is still a v3 build on 20.1.5. mfe2 was rebuilt on v4 with 20.1.6. All accept ^20.1.0. The Orchestrator produced this import map, with no warnings:
{ "imports": { "@angular/core": "http://shell.example/core.js", "@angular/core/rxjs-interop": "http://shell.example/core-rxjs-interop.js", "@angular/router": "http://shell.example/router.js", "rxjs": "http://shell.example/rxjs.js", "mfe1/./Component": "http://mfe1.example/Component-v3.js", "mfe2/./Component": "http://mfe2.example/Component-v4.js" } } One Angular for the whole page. Under the v3 host, mfe1 and mfe2 would each have loaded their own Angular, because neither matched the host's version exactly.
The migration path
Step 0: get ready
- Check your Angular version. The v4 adapter needs Angular 20 or newer. If you're on Angular 19 or older, upgrade Angular first, or stay on v3 for now (v3 vs v4).
- Pick the right package name. On Angular 22, v4 ships as
@angular-architects/native-federation. On Angular 20 and 21, it ships as@angular-architects/native-federation-v4. The steps are the same, only the name differs. - Clear old caches. Mixing v3 build output with v4 output is the most common cause of "the app runs, but a file can't be found" errors (migration guide):
rm -rf .angular/ dist/ node_modules/.cache/ - Take stock. The five-minute check from Part 2 tells you which package and version each app is on.
Step 1: move the host to v4
Most of the work is automated. On Angular 22, run:
ng update @angular-architects/native-federation On Angular 20 or 21, run ng g @angular-architects/native-federation-v4:update-v4 instead (Angular migration guide). Either way, the migration:
- updates
package.jsonto the v4 packages, - renames
federation.config.jstofederation.config.mjsand switches it fromrequire()toimport, - updates the builder settings in
angular.json.
Two manual clean-ups are worth doing at the same time. Remove @softarc/native-federation-runtime, the end-of-life Classic Runtime, from package.json. Then add the Orchestrator package:
"@softarc/native-federation-orchestrator": "^4.10.0" Here's the part that surprises most teams: on Angular 22, main.ts doesn't need to change. The adapter's own initFederation() now runs the Orchestrator under the hood, so your host gets version ranges, share scopes and caching without touching that call (Angular migration guide). On Angular 20 and 21, only the import path changes to the -v4 package.
Deploy the host, and the page is now running on v4. Your remotes haven't changed at all.
Step 2: use the loader initFederation() returns
In v3, you imported loadRemoteModule from the runtime package anywhere in your code. In v4, that global function still works, but it's deprecated. It depends on a hidden, module-level instance, which makes it brittle in tests and in apps with more than one host.
This step is a manual change. The main.ts that ng add and ng update generate still throws away what initFederation() returns. Notice the _ (getting started):
// main.ts, as generated initFederation('federation.manifest.json', { hostRemoteEntry: { url: './remoteEntry.json' }, }) .catch(err => console.error(err)) .then(_ => import('./bootstrap')) .catch(err => console.error(err)); With this version, your routes keep using the deprecated global loadRemoteModule. It works, which is why you can do this step later.
The recommended v4 way is to keep the result, called nf below, and hand it to Angular's dependency injection. This is the pattern from the official runtime docs, slightly shortened.
main.ts passes nf into bootstrap, instead of discarding it:
// main.ts, after the change import { initFederation, NativeFederationResult } from '@angular-architects/native-federation'; initFederation('federation.manifest.json', { hostRemoteEntry: { url: './remoteEntry.json' }, }) .then((nf: NativeFederationResult) => import('./bootstrap').then((m) => m.bootstrap(nf))) .catch((err) => console.error(err)); bootstrap.ts exports a bootstrap function that receives nf, instead of starting Angular straight away:
export const bootstrap = (nf: NativeFederationResult) => bootstrapApplication(AppComponent, appConfig(nf)); app.config.ts provides it through an InjectionToken, and builds the routes with it:
export const MODULE_LOADER = new InjectionToken<NativeFederationResult>('loader'); export const appConfig = (nf: NativeFederationResult): ApplicationConfig => ({ providers: [ { provide: MODULE_LOADER, useValue: nf }, provideRouter(routes(nf)), ], }); Routes receive it as a parameter, because they're created before Angular's injector exists:
export const routes = ({ loadRemoteModule }: NativeFederationResult): Routes => [ { path: 'orders', loadComponent: () => loadRemoteModule('mfe1', './Component').then((m) => m.AppComponent), }, ]; Anything else, such as a service, uses inject(MODULE_LOADER). Provide the whole result, not just loadRemoteModule. That way initRemoteEntry(), for remotes added later, is available everywhere too, and tests can swap in a fake.
Step 3: move the remotes, one at a time
Each remote team runs the same ng update and config change as the host, on their own schedule. As the test above showed, a page can mix v3 and v4 remotes for as long as the migration takes.
Two notes for this phase:
- A remote's
main.tsonly matters when the remote runs on its own, for example during local development. When a host loads it, only itsremoteEntry.jsonand exposed files are used. - Remotes that can't be rebuilt yet still work. If you later turn on
denseExternals(step 4), the host optionconvertFlatSharedInfohelps the Orchestrator read their older files (Part 5).
Step 4: tighten the settings
Once the host and most remotes are on v4, adopt the settings that v4 makes possible. Each one is explained in an earlier part:
-
keepAllandpool: 'angular'on@angular/*, so every remote can share one complete Angular (Part 5, Part 6):
shared: fromPackageJson({ singleton: true, strictVersion: true, requiredVersion: 'auto', build: 'package' }) .patch(['@angular/*'], { includeSecondaries: { keepAll: true }, pool: 'angular' }), -
features: { denseExternals: true }, starting with the host (Part 5). - Strict mode in staging, and
logLevel: 'warn'in production (Part 6).
Angular upgrades during the migration
A migration can take months, and Angular keeps releasing in the meantime. The mixed-page test above worked because every app accepted ^20.1.0. Two other cases need a plan. I ran both on Orchestrator 4.10.1.
A patch upgrade, remote first. ng update usually rewrites the range in package.json to the version it just installed, for example ^20.1.5. If mfe1 does that while the host is still on 20.1.4, its range now rejects the host's version, and it loads its own Angular. With the angular pool, the Orchestrator warns:
'mfe1' is islanded: its range rejects '@angular/core@20.1.4' of the elected build '__NF-HOST__'. Without the pool, nothing is logged at all. The fix is simple: update the host first, or with everyone else, so its version always fits the remotes' ranges.
A major upgrade. Here, the order doesn't save you. ^20.1.0 never accepts 21, and ^21.0.0 never accepts 20, so whoever is behind loses sharing until everyone has moved. With a host on 20.1.4 and mfe2 on 21.0.2:
- With
strictVersion: true,mfe2loads its own Angular 21, without any warning. That's two Angulars from different majors on one page. - With
strictVersion: false,mfe2, built for Angular 21, silently runs on Angular 20. Never usestrictVersion: falseon a framework.
A second Angular can't render inside the host's component tree (Part 5), so a major upgrade leaves two options:
- One coordinated release: the host and every remote move to the new major together. This is the simplest choice.
- A temporary island: one remote moves early and starts up as its own app, for example as a web component built with Angular Elements. Accept the extra download, and plan when it ends.
Remember the package names too: Angular 20 and 21 use @angular-architects/native-federation-v4, Angular 22 uses @angular-architects/native-federation.
What breaks, or will
- A CommonJS config. v4 is ES modules all the way through, so
require()andmodule.exportsmust becomeimportandexport default. The migration does this for you, and the.mjsname means you don't need to add"type": "module"topackage.json. - The global
loadRemoteModule. Deprecated, as covered in step 2. -
share(). Deprecated in core 4.10. UsefromPackageJson().only([...])to pick packages, and.override({...})to give them their own settings (Core configuration).shareAll()still works. -
importmap.json. The build still writes it, but nothing reads it anymore, and it's marked for removal in v5 (core source). Don't build tooling on top of it. - Hidden warnings. The Orchestrator logs only errors by default, so drift warnings stay invisible until you set
logLevel: 'warn'(Part 6). - Caching and reused URLs. If you turn on browser storage, a remote redeployed at the same URL can keep its old cached
remoteEntry.json(Part 5).
Rolling back
Because remotes don't change in step 1, rolling back the host is easy: redeploy the previous v3 host build. Your remotes keep working with either host.
There's one setting that closes this rollback window: denseExternals. A dense remoteEntry.json lists each package's files in a new entries field instead of the outFileName field. As Part 4 showed, the Classic Runtime only reads packageName, version and outFileName, so it can't use dense files. Turn on denseExternals in a remote only once every host that loads it runs v4. That's why it sits in step 4, not step 1.
A checklist for your migration plan
- [ ] Every app is on Angular 20 or newer, or has an Angular upgrade planned first.
- [ ] Each team knows which package name it needs:
native-federation(Angular 22) ornative-federation-v4(Angular 20–21). - [ ] Old caches are cleared before the first v4 build.
- [ ] The host moves first, and
@softarc/native-federation-runtimeis removed. - [ ] Code uses the loader returned by
initFederation(), provided through anInjectionToken. - [ ] Remotes move one at a time, and each one is tested against the v4 host.
- [ ] Angular patch updates reach the host first, and major updates are released together or as a planned island.
- [ ]
denseExternalsis turned on only after every host runs v4. - [ ]
keepAll,pool, strict mode in staging andlogLevel: 'warn'are in place.
The final part brings everything together: a reference architecture for running Native Federation v4 in a regulated enterprise.
Series roadmap
- The Mental Model, Revisited: why Native Federation exists and what changed in v4
- Anatomy of the v4 Package Graph: Core, Adapters, Runtime and Orchestrator as separate layers
- Build-Time, End to End: from
federation.configtoremoteEntry.json - The Classic (v3) Runtime: what it got right, and where it hit its limit
- The Orchestrator: how v4 decides what loads, and what changed in 4.8.0
- Version Drift and Resolution Strategy: keeping independently deployed apps in sync
- v3 vs. v4: a practical plan for migrating, one app at a time (this article)
- Reference Architecture: running Native Federation v4 in a regulated enterprise
Further reading
Official documentation
- v3 vs v4
- Migration to v4
- Angular adapter: migration to v4
- Angular adapter: runtime, including wiring the result into Angular
- Angular adapter: schematics (
update22andupdate-v4) - Core: configuration
- Orchestrator overview
Source code
- Angular adapter's
initFederation()and the deprecated globalloadRemoteModule - Core 4.10.1 deprecations (config.ts)
Next in this series: **Reference Architecture, running Native Federation v4 in a regulated enterprise.

