Skip to content

CONCEPT Cited by 1 source

Shared singleton dependency

Definition

A shared singleton dependency is a library that must have exactly one module instance on the page even when multiple independently built bundles each declare a dependency on it. The canonical example is React: context providers, hooks state, and the fiber tree all assume one React instance. Two Reacts on the same page silently break useState, context propagation, and React.memo equality.

In Webpack Module Federation, the singleton semantic is made explicit by marking a library singleton: true in the shared configuration:

shared: {
  react:       { singleton: true, eager: true },
  "react-dom": { singleton: true, eager: true },
  lodash:      {},  // shared, but duplicate copies tolerated
}

At runtime, Module Federation's version-negotiation logic:

  • Without singleton: true — each bundle that requests the library gets a version it's compatible with; if compatible versions diverge, multiple copies may load. Fine for stateless utility libraries.
  • With singleton: true — only one version loads for the whole page. If the host and a remote declare incompatible versions, federation emits a warning or error rather than silently duplicating. The host usually wins the version race.

Why it is load-bearing

The failure mode of not using singleton for stateful libraries is subtle and hard to debug:

  • React.createContext from copy A is not identity-equal to React.createContext from copy B, so a Provider from one and a useContext in the other never connect.
  • Hooks store state in the currently rendering fiber; two Reacts have two independent fiber roots and two independent dispatcher queues.
  • instanceof checks (e.g. instanceof Element) against the wrong React see the wrong class.

The observable symptom is usually "my hook returns undefined from inside the remote but works in a standalone render" or "the context value is the default" — never a clean error. This is why Module Federation deployments universally make React / React-DOM singletons even when they tolerate duplicates for utility libraries.

Version-skew constraint

Singleton shifts the version-drift problem from duplication to negotiation. If the host upgrades React 18 → 19 but a team's remote still bundles React 18, federation must pick one and the other may hit runtime errors (e.g. new hooks missing, or new behaviour on existing APIs). Teams in Module-Federation deployments typically align React majors across all remotes during development and coordinate upgrades.

Seen in

  • sources/2024-10-16-zalando-building-a-modular-portal-with-webpack-module-federation — Zalando's Logistics Portal marks React and React-DOM as shared singletons across the host + 11 remotes. The post's own framing: "By marking key libraries (e.g. React, lodash) as shared, we were able to reduce version conflicts and avoid loading multiple versions of the same package. Additionally, we worked on aligning versions across teams during development to maintain consistency and minimise potential issues." Runtime singleton plus development-time version alignment is the working combination.
Last updated · 550 distilled / 1,221 read