react-lifecycles-compat

react-lifecycles-compat is a small backwards-compatibility polyfill that lets class components use the newer React lifecycles — getDerivedStateFromProps and getSnapshotBeforeUpdate, introduced in React 16.3 — while still running on React as old as 0.14.9. It is primarily meant for shared library authors who need to support a wide range of React versions without shipping a breaking major release.

You write your component against the modern static lifecycle API, then wrap the class with the exported polyfill function. On older React it wires the new methods to the legacy componentWill* lifecycles; on newer React it defers to the native implementations. It also throws helpful errors when a component mixes new and unsafe legacy lifecycles in ways that would behave inconsistently.

What You Get

• A single polyfill() higher-order function that upgrades a class component in place
• Support for getDerivedStateFromProps and getSnapshotBeforeUpdate down to React 0.14.9
• Automatic no-op behaviour on React 16.3+ where the new lifecycles are native
• Guardrail errors when new and unsafe legacy lifecycles are mixed incorrectly
• CommonJS and ES module builds with zero runtime dependencies

Common Use Cases

• Letting a shared component library support both old and new React versions
• Adopting getDerivedStateFromProps without dropping support for React < 16.3
• Migrating away from deprecated componentWill* lifecycles safely
• Avoiding a breaking major release when modernizing a library’s lifecycle usage

Under The Hood

Architecture - The whole library is index.js exporting polyfill(Component). It validates the target is a React class component, returns early if neither new lifecycle is defined, and throws if the component also defines conflicting legacy or UNSAFE_ lifecycles. When getDerivedStateFromProps exists it assigns shim componentWillMount/componentWillReceiveProps that call the static method via setState; when getSnapshotBeforeUpdate exists it assigns a componentWillUpdate shim that stashes the snapshot on internal flags and wraps componentDidUpdate to forward the correct snapshot value across React versions.

Tech Stack - Plain JavaScript authored by the React team (Facebook), bundled with Rollup into CommonJS (.cjs.js) and ES module (.es.js) outputs. It has no runtime dependencies and lists React as a peer.

Code Quality - The implementation is heavily commented, explaining each React-version edge case (falsy snapshots, prevContext confusion on React <= 15, shallow-renderer binding). It ships a test.js suite and the shim toggling logic is precise about not double-invoking lifecycles on modern React.

API Design - The public surface is one function you call on your component class, which keeps adoption trivial: write modern lifecycles, wrap once, done. The deliberate error messages when mixing incompatible lifecycles turn a subtle runtime footgun into an immediate, explanatory failure.