v3 vs v4

Native Federation v4 is a significant upgrade — new packages, full ESM, a new recommended runtime, and a new GitHub home. This page summarises every breaking change and new capability in one place so you know exactly what to expect before diving into a section of the docs.

Repositories

v4 moves to a new GitHub organisation. The v3 source stays in the original Angular Architects monorepo.

V3 monorepo

V4 repositories

At a Glance

Package Names

The core packages keep the same name but bump their major version. The Angular adapter's package name depends on your Angular version — it was published under a -v4 name during the Angular 20/21 cycle and reverts to its original name on Angular 22:

Angular Version

The v4 Angular adapter targets Angular 20 and above, with one backwards-compatible major. If you are on Angular 14–19 and cannot upgrade Angular yet, stay on v3.

v4 is stable. On Angular 22 it ships as the base package @angular-architects/native-federation (22.x). On Angular 20 and 21 the same adapter is published under @angular-architects/native-federation-v4, so you can adopt v4 early without overwriting an existing v3 install. Moving from -v4 (or straight from v3) to Angular 22 is a single ng update @angular-architects/native-federation — see Angular Adapter → Updating to Angular 22.

Full ESM

v4 drops CommonJS in every package. The change you need is in one file:

1. federation.config.(m)js — rename it to federation.config.mjs and switch from require() / module.exports to import / export default, updating the import path to the v4 adapter package.
2. package.json — bump the dependencies to their v4 majors. You do not need "type": "module"; the .mjs extension already makes the config ESM. Adding it is optional and only matters if you want the whole workspace to default to ESM.

The Migration to v4 guide walks through these two changes step by step. The Angular-specific parts are in Angular Adapter → Migration to v4.

Runtime: Orchestrator vs Classic

v3 shipped one browser runtime: the Classic Runtime (@softarc/native-federation-runtime). It resolves shared dependencies at startup, wires a single import map, and loads remotes on demand. Simple and battle-tested.

v4 introduces the Orchestrator (@softarc/native-federation-orchestrator) as the recommended replacement. It keeps the same remoteEntry.json contract but adds:

• Semver-range resolution — remotes that declare different version ranges of the same package are reconciled automatically, rather than requiring byte-identical version strings.
• Persistent caching — remoteEntry.json files are cached in localStorage or sessionStorage, so the manifest fetch is skipped on repeat visits.
• Share scopes — fine-grained sharing boundaries for complex multi-team setups.

The Classic Runtime is still fully supported in v4 and remains the right choice when you need SSR on the host or want the simplest possible setup. It is not deprecated — but new v4 projects should prefer the Orchestrator.

Migrating

• Migration to v4 — the framework-agnostic steps (ESM, package.json, federation.config.js).
• Angular Adapter → Migration to v4 — Angular-specific steps (builder rename, angular.json, main.ts). Includes the update-v4 schematic that automates most of the work.