In a Module Federation setup, what does marking a shared dependency like react as singleton: true with a requiredVersion do, and what happens if a host and remote have incompatible versions?

## What singleton actually promises The `shared` option in `ModuleFederationPlugin` tells Webpack which libraries a host and its remotes should attempt to reuse a single instance of at runtime instead of each bundle shipping and loading its own private copy. Marking an entry like `react` with `singleton: true` is a strict instruction: at most one instance of that library may ever be active in the shared scope at a time, no matter how many federated apps request it. This matters because libraries like React and React DOM keep module-level mutable state (the fiber tree, hook dispatcher, context registries) that breaks in confusing ways if two separate copies end up mounted in the same page even though each one is individually valid code, such as - 'Invalid hook call' errors, - context providers that don't reach consumers, - or duplicated event listeners. ## How version negotiation works The mechanism behind this is version negotiation through what Webpack calls the **shared scope**, effectively a runtime registry keyed by package name and semver range. 1. When a federated app initializes, its container's `init(shareScope)` runs, it registers every entry from its own `shared` config into that scope, announcing 'I have [email protected] and I need a version satisfying ^18.0.0.' 2. As each app in the composition does this, Webpack's runtime resolves, for each shared package name, which single concrete version satisfies the most requesters and actually loads only that one module graph, handing out the same live module object to every consumer that asked for a compatible range. `requiredVersion` is what defines the acceptable semver range for a given app's request, defaulting to whatever's in its own package.json if omitted, and `strictVersion` controls whether an unsatisfiable range throws at runtime or falls back to a bundled-in copy. ## When the versions genuinely clash When a host and remote declare genuinely incompatible required versions for a singleton — say the host is pinned to react@^17 and a newly deployed remote requires react@^18 — Webpack's runtime has to pick one behavior. | Setting | What the runtime does | The reasoning | |---|---|---| | `strictVersion: true`, common for singletons | throws a runtime error during initialization rather than silently loading two React copies | for a `singleton: true` package silently violating the singleton guarantee is considered worse than failing loudly | | `strictVersion: false`, or when singleton isn't set | lets the requester fall back to a self-contained copy bundled into that app | restoring correctness for that one app at the cost of shipping duplicate library weight and losing the 'single instance' guarantee its own config had implied | For something like a router or global state library this can produce very hard-to-diagnose bugs, because the app runs without error but two independent module instances silently diverge in state. ## Why the system exists at all This system exists because Module Federation's whole value proposition — independently deployed apps composing into one page as if they were one app — collapses if every remote drags in its own multi-hundred-kilobyte copy of the UI framework: bundle size balloons, and framework-level singleton state breaks across the composed page. Sharing gives back both the bundle-size win of a monorepo and, when versions line up, framework-level continuity across independently built apps, at the cost of a genuinely hard operational problem: every team touching a shared dependency's major version now has an implicit cross-team compatibility contract, even though nothing in their separate CI pipelines enforces it before deploy. ## How teams manage it in practice In practice, teams manage this by: - **treating shared, singleton dependencies** as a slow-moving, centrally governed layer — often pinning exact ranges for React, React DOM, and a shared router across every remote and coordinating major version bumps as a cross-team migration rather than a per-app decision, - while **leaving smaller, less state-sensitive libraries** either un-shared, each app bundles its own, or shared but non-singleton, where duplication is a bundle-size cost rather than a correctness risk. A concrete example: a large B2B console with a shell and eight remotes shares react, react-dom, and their design-system package as strict singletons pinned to one version, but leaves date-formatting or charting libraries un-shared, accepting the extra kilobytes so any single team can upgrade its own chart library without a fleet-wide coordination effort.