DEV Community

Sakthikumaran Navakumar
Sakthikumaran Navakumar

Posted on

Native Federation - Deep Dive - Part 7/8 - v3 vs. v4 - A Practical Plan for Migrating Native Federation, One App at a Time

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"
  }
}
Enter fullscreen mode Exit fullscreen mode

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.

One page mid-migration: the shell is a v4 host running Orchestrator 4.10 with Angular 20.1.4, mfe1 is still a v3 build on Angular 20.1.5, and mfe2 was rebuilt on v4 with Angular 20.1.6. All three use one shared Angular 20.1.4 from the host's build.

The migration path

The migration path. Step 0: get ready, with Angular 20 or newer and old caches cleared. Step 1: move the host to v4 with ng update and federation.config.mjs; the host now runs the Orchestrator and remotes stay on v3. Step 2: use the returned loader by passing initFederation's result through an InjectionToken. Step 3: move remotes one by one, each team on its own schedule, with v3 and v4 remotes mixed on one page. Step 4: tighten the settings with keepAll and pool on @angular/*, denseExternals, and strict mode in staging.

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/
Enter fullscreen mode Exit fullscreen mode
  • 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
Enter fullscreen mode Exit fullscreen mode

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.json to the v4 packages,
  • renames federation.config.js to federation.config.mjs and switches it from require() to import,
  • 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"
Enter fullscreen mode Exit fullscreen mode

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));
Enter fullscreen mode Exit fullscreen mode

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));
Enter fullscreen mode Exit fullscreen mode

bootstrap.ts exports a bootstrap function that receives nf, instead of starting Angular straight away:

export const bootstrap = (nf: NativeFederationResult) =>
  bootstrapApplication(AppComponent, appConfig(nf));
Enter fullscreen mode Exit fullscreen mode

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)),
  ],
});
Enter fullscreen mode Exit fullscreen mode

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),
  },
];
Enter fullscreen mode Exit fullscreen mode

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.ts only matters when the remote runs on its own, for example during local development. When a host loads it, only its remoteEntry.json and exposed files are used.
  • Remotes that can't be rebuilt yet still work. If you later turn on denseExternals (step 4), the host option convertFlatSharedInfo helps 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:

  • keepAll and pool: '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' }),
Enter fullscreen mode Exit fullscreen mode
  • 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__'.
Enter fullscreen mode Exit fullscreen mode

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, mfe2 loads 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 use strictVersion: false on 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() and module.exports must become import and export default. The migration does this for you, and the .mjs name means you don't need to add "type": "module" to package.json.
  • The global loadRemoteModule. Deprecated, as covered in step 2.
  • share(). Deprecated in core 4.10. Use fromPackageJson().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) or native-federation-v4 (Angular 20–21).
  • [ ] Old caches are cleared before the first v4 build.
  • [ ] The host moves first, and @softarc/native-federation-runtime is removed.
  • [ ] Code uses the loader returned by initFederation(), provided through an InjectionToken.
  • [ ] 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.
  • [ ] denseExternals is turned on only after every host runs v4.
  • [ ] keepAll, pool, strict mode in staging and logLevel: 'warn' are in place.

The final part brings everything together: a reference architecture for running Native Federation v4 in a regulated enterprise.

Series roadmap

  1. The Mental Model, Revisited: why Native Federation exists and what changed in v4
  2. Anatomy of the v4 Package Graph: Core, Adapters, Runtime and Orchestrator as separate layers
  3. Build-Time, End to End: from federation.config to remoteEntry.json
  4. The Classic (v3) Runtime: what it got right, and where it hit its limit
  5. The Orchestrator: how v4 decides what loads, and what changed in 4.8.0
  6. Version Drift and Resolution Strategy: keeping independently deployed apps in sync
  7. v3 vs. v4: a practical plan for migrating, one app at a time (this article)
  8. Reference Architecture: running Native Federation v4 in a regulated enterprise

Further reading

Official documentation

  1. v3 vs v4
  2. Migration to v4
  3. Angular adapter: migration to v4
  4. Angular adapter: runtime, including wiring the result into Angular
  5. Angular adapter: schematics (update22 and update-v4)
  6. Core: configuration
  7. Orchestrator overview

Source code

  1. Angular adapter's initFederation() and the deprecated global loadRemoteModule
  2. Core 4.10.1 deprecations (config.ts)

Next in this series: **Reference Architecture, running Native Federation v4 in a regulated enterprise.

Top comments (0)