Orchestrator 4.8.0: one build per package (no more "stitching")

[Aukevanoost]

We will stop supporting unstable dependency entrypoint "stitching"!

Orchestrator 4.8.0 changes how a shared package is assembled in the browser. Most pages won't notice. Some pages
will download a few more files, and pages built with flat externals (still the default) can lose more of their
sharing than before. This post explains what changed, why, what it costs, and how to grow your setup to a more robust architecture with us!

But we want to know what you think, post your thoughts, ideas and comments.

TL;DR

• A remote (micro frontend) now runs every entrypoint of a shared external ( a package like @angular/core, @angular/core/rxjs-interop, …)
  from one build (read: the remoteEntry.json). The orchestrator no longer "borrows" a missing entrypoint from another remote's (read: micro frontend) build if the remote from the shared external happens to not export it.
• This fixes hard-to-trace runtime errors such as Angular's NG0203, which could show up long after the page loaded.
• The cost: a remote whose entrypoints the shared build doesn't fully cover now runs that whole package from its own
  build. That means more downloads and, for singletons like Angular, potentially a second instance on the page.
• The fix on your side: build with denseExternals and share coupled frameworks with
  includeSecondaries: { keepAll: true }. Then every build ships the same entrypoints and nothing has to fall back.
• In v5 (hopefully around the end of Q1 2027) we plan to make dense externals the default, and (when possible) drop flat externals entirely.
  Until then, flat externals stay fully supported. But they will degrade performance (more stitching/resolving magic necessary from the orchestrator to make flat and dense work together).

What is "stitching"?

A shared package usually has more than one entrypoint: @angular/core has @angular/core/rxjs-interop,
@angular/core/testing and others. By default, Native Federation only publishes the entrypoints a build actually
imports (ignoreUnusedDeps feature). So two micro frontends on the same Angular version can publish different sets:

build	publishes
host	@angular/core
mfe1	@angular/core, @angular/core/rxjs-interop

The orchestrator generates one import map for the page, with one shared version of @angular/core. Up to 4.7.x, when
the shared build (here: the host's) didn't have @angular/core/rxjs-interop, the orchestrator took it from mfe1's
build instead, since it's the same version anyway. One package, assembled from two builds: that's what we call stitching.

It looks harmless: same package, same version. It isn't, for two reasons.

Problem 1: chunks bring their own copy of the internals

Shared packages are code-split. An entrypoint doesn't contain all its code; it imports internal chunks from its own
build. A borrowed entrypoint therefore brings a second copy of the package's internals along:

flowchart LR
  subgraph code["1 · code on the page"]
    hostApp["host app<br/>bootstraps Angular"]
    cmp["mfe1 component<br/>inject() + toSignal()"]
  end

  subgraph map["2 · import map"]
    kCore["@angular/core"]
    kInterop["@angular/core/rxjs-interop"]
  end

  subgraph files["3 · entrypoint files"]
    subgraph hostB["host build"]
      core["core.js"]
    end
    subgraph mfeB["mfe1 build (borrowed)"]
      interop["rxjs-interop.js"]
    end
  end

  subgraph chunks["4 · internal chunks"]
    chA["host: chunk-A.js<br/>Angular runtime #1<br/>holds the injection context"]
    chB["mfe1: chunk-B.js<br/>Angular runtime #2<br/>knows no injection context"]
  end

  err["NG0203<br/>inject() must be called<br/>from an injection context"]

  hostApp --> kCore
  cmp --> kCore
  cmp --> kInterop
  kCore --> core
  kInterop --> interop
  core --> chA
  interop --> chB
  chB -. "toSignal() calls inject()<br/>on runtime #2" .-> err

  classDef borrowed fill:#fde2e1,stroke:#c0392b,color:#000
  classDef error fill:#c0392b,stroke:#c0392b,color:#fff
  class kInterop,interop,chB borrowed
  class err error

Loading

toSignal() now runs against a different Angular runtime than the rest of the component: NG0203. Worse, the page
renders fine at first. It only breaks once the code path that uses the borrowed entrypoint runs, so it can easily
slip past testing.

Problem 2: a borrowed file uses the lender's dependencies

The import map resolves a bare import by the URL of the file that imports it, not by the micro frontend that started
the import chain. A borrowed file therefore resolves its own imports through the lender's scope:

flowchart LR
  subgraph code["1 · code on the page"]
    cmp["mfe2 component<br/>imports @my-org/lib/feature<br/>and rxjs"]
  end

  subgraph map["2 · import map"]
    subgraph global["imports (global)"]
      gFeature["@my-org/lib/feature"]
      gRx["rxjs"]
    end
    subgraph scope["scope: mfe1's URL"]
      sRx["rxjs"]
    end
  end

  subgraph files["3 · files"]
    subgraph hostB["host build"]
      rx7file["rxjs.js (7.8)"]
    end
    subgraph mfeB["mfe1 build (borrowed)"]
      feature["feature.js"]
      rx6file["rxjs.js (6.6)"]
    end
  end

  subgraph runs["4 · what runs"]
    rx7["rxjs 7<br/>what mfe2 asked for"]
    rx6["rxjs 6<br/>what mfe2 gets via the feature"]
  end

  err["mfe2 mixes rxjs 6 and 7:<br/>operators and Observables<br/>from two instances"]

  cmp --> gFeature
  cmp --> gRx
  gFeature --> feature
  gRx --> rx7file
  feature -. "its import of rxjs resolves<br/>by its own URL" .-> sRx
  sRx --> rx6file
  rx7file --> rx7
  rx6file --> rx6
  rx6 -.-> err
  rx7 -.-> err

  classDef borrowed fill:#fde2e1,stroke:#c0392b,color:#000
  classDef error fill:#c0392b,stroke:#c0392b,color:#fff
  class gFeature,feature,sRx,rx6file,rx6 borrowed
  class err error

Loading

mfe2 asked for rxjs 7, but everything it reaches through the borrowed file runs on rxjs 6.

Stitching relied on "same version = same files". In a real portfolio we measured, 7 of 24 (package, version) pairs
shipped different file sets across builds. Same version doesn't mean same artefact.

The rule in 4.8.0

A micro frontend resolves every entrypoint of a package from one build. A build that lacks an entrypoint never
borrows it from another build.

• Per share scope, every package has one serving build: the host's when it has one, otherwise the build that
  causes the fewest extra downloads and the fewest fallbacks.
• A remote whose entrypoints that build fully covers takes the package from it, as before.
• A remote it doesn't fully cover runs the whole package from its own build. For a pooled package (pool label),
  that's the whole pool: e.g. all of @angular/*.
• Runtime loads (initRemoteEntry) and getShared follow the same rule.

flowchart LR
  subgraph host["host build"]
    core["@angular/core"]
  end

  subgraph mfe1["mfe1 build"]
    core1["@angular/core"]
    interop1["@angular/core/rxjs-interop"]
  end

  h["host"] --> core
  m2["mfe2: only imports @angular/core"] --> core
  m1["mfe1: imports rxjs-interop too"] --> core1
  m1 --> interop1

Loading

The trade-off: coherence over downloads

Every remote now runs each package coherently, from one build. The price is paid where the shared build doesn't cover
a remote:

• More downloads. The remote downloads its own copy of the package instead of borrowing one entrypoint. Measured
  over 340 generated portfolios: remotes running a package from two builds went from 40 to 0, for about +0.4%
  downloads. On a real eleven-remote Angular portfolio, the @angular/* files loaded at init went from 54 (stitched)
  to 63; still fewer than the 75 of 4.7.0.
• More duplicates. For a singleton like Angular, the remote now runs a second framework instance next to the
  host's. That's coherent for the remote itself, but its components can't be rendered inside the host's component tree
  (which shares DI with the host's instance). Before, the page looked like it shared one Angular and then broke on a
  code path; now the duplicate is real and visible in the record and logs.
• Bigger import maps. Every remote that falls back gets its own scope for the package. On pages where many remotes
  fall back, the import map can grow up to twice as large and a cold init at 100 remotes takes about 1.3–1.4× as
  long. Without fallbacks, the import map is unchanged and init is about 5 ms slower at 100 remotes.

All three costs come from the same thing: builds that publish different entrypoint sets of the same package.
Remove that, and nothing has to fall back.

Why flat externals make this worse

Native Federation can describe shared packages in remoteEntry.json in two ways:

• Flat (the current default): every entrypoint is its own shared external, with its own version, range and
  flags. @angular/core and @angular/core/rxjs-interop are two unrelated entries; the orchestrator has to piece the
  package together from the specifier names.
• Dense (opt-in, features.denseExternals: true): one object per package, with an entries map of all its
  entrypoints and one set of metadata.

// flat
{ "packageName": "@angular/core",               "version": "20.0.0", "requiredVersion": "^20.0.0", "outFileName": "core.js" },
{ "packageName": "@angular/core/rxjs-interop",  "version": "20.0.0", "requiredVersion": "^20.0.0", "outFileName": "rxjs-interop.js" }

// dense
{
  "packageName": "@angular/core", "version": "20.0.0", "requiredVersion": "^20.0.0",
  "entries": { "@angular/core": "core.js", "@angular/core/rxjs-interop": "rxjs-interop.js" }
}

Under stitching, flat entries were mostly harmless: each entrypoint was negotiated on its own and gaps were patched
by borrowing. Under "one build per package", any disagreement between the loose parts splits the package, and a
split package falls back as a whole:

• one flat entrypoint whose strictVersion range rejects the shared version moves the whole package to the remote's
  own build, even where the serving build ships both;
• an entrypoint stamped with another version than its root (e.g. a wildcard secondary, native-federation-core#169)
  makes the build look like it ships the package at two versions, so it can't serve anyone else and runs the package
  from its own build;
• a pool label on one flat entry has to be extended to its siblings by name;
• every fallback scopes each flat entrypoint separately, which is where the import map growth comes from.

With dense externals a package is one unit with one version and one range, so the orchestrator decides it once.

How to avoid fallbacks

Two settings in your federation.config.mjs, applied to every build in the portfolio, the host first:

import { withNativeFederation, fromPackageJson } from '@softarc/native-federation/config';

export default withNativeFederation({
  name: 'mfe1',
  exposes: { /* … */ },

  shared: fromPackageJson({ singleton: true, strictVersion: true, requiredVersion: 'auto', build: 'package' })
    .patch(['@angular/*'], { includeSecondaries: { keepAll: true } })
    .get(),

  features: {
    denseExternals: true,
  },
});

• denseExternals: true publishes every package as one dense object (see above).
• includeSecondaries: { keepAll: true } on @angular/* publishes every secondary entrypoint of each Angular
  package the build uses, not only the ones it happens to import. Every build on the same Angular version then ships
  the same entrypoints, so the host's build covers every remote and nobody has to fall back. Use it for tightly
  coupled framework packages (Angular, your design system); leave it off for utility libraries whose secondaries are
  independent.
• build: 'package' bundles each package with its own secondaries, so a package's chunks belong to that package
  only.

Note

Wildcard patterns like '@angular/*' in .patch() are supported since Native Federation 4.8.0. They match the
dependency names in your package.json, and a secondary entrypoint inherits its package's patch. On older versions,
.patch() only takes exact package names, so list every package individually:

.patch(
  ['@angular/core', '@angular/common', '@angular/router', '@angular/forms',
   '@angular/platform-browser', '@angular/animations' /* , … every @angular/* dependency */],
  { includeSecondaries: { keepAll: true } }
)

Remotes that render inside the host's component tree should stay on the host's build: align their versions and
ranges with the host's.

Can't rebuild every remote yet? convertFlatSharedInfo

For remotes that still publish flat externals (an older build, or one owned by another team), the orchestrator can
densify their remoteEntry.json when it fetches it:

await initFederation(manifest, {
  feature: {
    convertFlatSharedInfo: true,
  },
});

It groups each flat secondary entrypoint under its parent package, so @angular/core/rxjs-interop joins
@angular/core as one dense external, just like a denseExternals build would publish it. Remotes that are
already dense pass through unchanged, so you can switch it on while you migrate your builds one at a time.

It only regroups what the build declared:

• entrypoints are grouped only when all their metadata matches (version, requiredVersion, strictVersion,
  singleton, shareScope, pool, …). An entrypoint stamped with another version than its root stays a separate
  external and still splits the package;
• it can't add entrypoints a build pruned, so you still need keepAll in the builds to avoid fallbacks.

Rebuilding with denseExternals remains the real fix; convertFlatSharedInfo bridges the remotes you can't rebuild
yet.

Shared mappings: name them like packages

The same rule applies to your own monorepo libraries (sharedMappings). Neither Native Federation nor the
orchestrator has a package.json to tell them which entrypoints belong together, so they go by the name:
@my-org/shared/ui and @my-org/shared/util are two entrypoints of one package, @my-org/shared. That decides
what build: 'package' bundles together, what denseExternals groups, and, since 4.8.0, what the orchestrator
serves from one build.

This matters most when your libraries carry their own versions (mappingVersion, on by default, stamps every mapping
with the version of its nearest package.json):

mapping	version	package
@my-org/shared/ui	1.0.0	@my-org/shared
@my-org/shared/util	2.0.0	@my-org/shared

To the orchestrator, that build ships one package at two versions. It can't serve that as one package to anyone else,
so the remote runs the whole package from its own build. Name independently versioned libraries as separate packages
instead (@my-org/ui, @my-org/util), and use subpaths only for entrypoints of one library that are versioned
together.

Names that don't follow npm package naming (@shared, ~app/utils, @My-Org/UI) have no package to be grouped
under. Native Federation 4.8.0 now warns about them at build time:

Shared mapping '@shared' does not follow npm package naming. Name mappings 'package' or '@company/package'
(lowercase). Subpaths and wildcards ('@company/package/*') are allowed, but belong to that package:
build: 'package' bundles them together.

With features.strictImports: true (see below) this warning fails the build.

New in Native Federation 4.8.0: strictImports

With stitching gone, an entrypoint a build imports but doesn't declare in remoteEntry.json is never filled in from
another build: the import simply doesn't resolve at runtime. This happens when ignoreUnusedDeps misses a dynamic
import(). Angular's provideAnimationsAsync() is the known case: it loads @angular/animations/browser dynamically,
the default build prunes it, and the host's animations silently never run.

Native Federation 4.8.0 now checks this at build time. After writing remoteEntry.json, it scans every published
file (shared bundles, mappings, exposed modules, chunks) and warns about every bare import that remoteEntry.json
doesn't declare. Turn the warning into a build error with:

features: {
  strictImports: true,
}

Fix a reported import with includeSecondaries: { keepAll: true } on its package, or by removing it from skip.

Roadmap

version	when	what
4.5.0	July 2026	First support for dependency pooling.
4.8.0	now	Pools elected as one build family; one build per package (no stitching). Flat and dense externals both supported.
5.0.0	around end of Q1 2027	Dense externals become the default (flat opt-in), or flat externals are no longer supported.

Until v5, flat externals keep working as they do in 4.8.0. We recommend switching to denseExternals now: it's
backwards compatible (the orchestrator reads both shapes, so you can migrate one build at a time) and it's what v5
will expect.

Feedback

We'd like to hear from you:

• Do you still depend on flat externals? Would dropping them in v5 block you, or is "dense by default, flat opt-in"
  enough?
• Did 4.8.0 make a remote fall back that you didn't expect? Please share the remote entries (or the orchestrator's
  debug state dump) so we can see why.

Background and measurements: native-federation/orchestrator#102.

[denatys]

Our case, after trying 4.8.0 on a monorepo with ~20 remotes:

Our workspace libraries share name prefixes without belonging together, e.g. @shared/components/table and @shared/components/collapse are independent libraries. 4.8.0 treats each prefix as one package. The shell publishes only the libraries it imports, so it covers almost no remote, and each remote runs the whole prefix from its own build.

With identical builds, going from 4.7.0 to 4.8.0 gave us:

• scoped import map entries: 1,260 → 3,020
• 27 libraries loaded twice on the same page, including root services and injection tokens
• no console errors, so it only showed up when we counted fetched files

We looked at the fix you suggest and it doesn't fit us:

• Covering every package from the shell. The shell would have to publish about 280 libraries it never imports.
• includeSecondaries on mappings. Libraries outside an app's TypeScript program fail the Angular compiler.
• Renaming every library into its own package. Possible, but a large refactor for a sharing setting.

For now we stay on orchestrator 4.7.0. Would you consider a way to declare which mappings form one package, or to opt out of the name-based grouping for mappings?

And a direct question: should we prepare for a mass rename? It would hurt us. The slashes in our mapping names show a library's domain (@events/evaluation/scoring/data, @shared/services/file-upload/core), not a package with entry points. If name-based grouping stays in v5, we'd rather know now.

[Aukevanoost]

Hi @denatys, thanks for this, there's a lot to unpack here, and thanks for measuring. Let me know if I got something wrong:

First off: fair point, it seems like for your setup 4.8.0 is a regression. Please correct me if I'm wrong but 27 libraries with root services and injection tokens loaded twice, silently, is exactly the failure mode "one build per package" was meant to remove. It just showed up one level higher. I do want you to know that we're not taking this migration lightly, v5 is not meant as a "we're forcing a different way of naming packages now" but more of an "we should provide robust shared externals" way. The sharedMappings has always been the unstable weak link in this.

Why it happens to you. As you might've figured out, your mapping names are valid npm names: @shared/components/table reads as the package @shared/components with a subpath table. That's why you get no warning. The build and the orchestrator both decide the package from the name, so independent libraries under one prefix become one package. If your shell doesn't import all of them, every remote that does runs the whole prefix from its own build.

Should you prepare for a mass rename? For now? No. Using slashes to show the domain seems like a legitimate convention, and a sharing setting shouldn't force you to rename 300 libraries. While I don't think deviating from the "npm standard" is the best solution, I want to explore how we (nf) can provide support.

What I'm looking at. A dense external already names its package separately from its entrypoints (packageName vs entries), so it can carry a real boundary, which a flat entry can't. The idea I'm working on:

• the build declares a mapping as its own package, even when its name is deeper than an npm name;
• the orchestrator, behind an opt-in flag, trusts that declaration for dense entries, and keeps the name rule for flat ones.

There's one condition: the 'boundary' has to be at the bundle level. If two libraries (read: sharedMappings) are built in the same bundle, they can share code-split chunks. Serving one from the shell and the other from a remote would load those chunks twice, which is stitching again under a different name. So this would likely be tied to mappings that get their own bundle (build: 'separate'). For a workspace your size that means many more bundler runs, might not be too bad but it is a performance penalty. Oh and this will only work for our denseExternals flag true, because that allows us to determine what is a package without having to defer from the name.

No timeline yet, but I've added it to our list for before v5. So I'll hope to get back to you about this ASAP.

To help us design it, could you share:

• roughly how many mappings you have, and how many prefixes they fall under (@shared/components, @events/evaluation, ...); whether you use the default single mapping bundle or
• whether denseExternals is on;
• whether your libraries have their own package.json

On includeSecondaries on mappings failing the Angular compiler: could you share the error? Publishing libraries an app doesn't import should work, so that sounds like a separate bug worth fixing on its own.

Hope this helps, feel free to share your ideas/opinions.

[denatys]

Thanks, that's very helpful, and good to hear a rename isn't needed.

Answers:

• Mappings: 980 mappings under 397 prefixes. 161 prefixes hold more than one mapping (744 mappings in total). In 45 of them apps publish different sets of libraries; 33 of those were split in the import map we measured.
• Mapping bundle: the default single mapping bundle; we don't set build for mappings.
• denseExternals: off. We turned it off on orchestrator 4.6.0: it chose a provider by coverage rather than manifest order, so a statically served remote could win over a dev-served one and serve stale library code in development.
• package.json: none of our libraries has one. They're plain TypeScript path mappings in one source tree.

Your direction fits us. We'd switch to denseExternals as long as the dev-server issue above doesn't come back, and we're happy to measure the extra bundler runs of build: 'separate' on our workspace once there's something to try.

The Angular error: we kept mappings with mappingsFromWorkspace().patch(list, { includeSecondaries: true }) (adapter 22.2.3, core 4.8.0). Our apps' tsconfig.app.json list only their entry files (src/main.ts and the routes file), so a library the app doesn't import is outside its TypeScript program. Files with Angular metadata then fail, the rest only get a warning:

✘ [ERROR] File 'libs/administration/sow-templates/feature/src/lib/sow-templates.component.ts' not found in TypeScript compilation. [plugin angular-compiler]

  Files containing Angular metadata ('@Component'/'@Directive'/etc.) must be part of the TypeScript compilation.