Deprecating a widely used component gracefully

WHAT THIS TESTS Whether you can balance moving the system forward with respecting semver and consumer effort, using communication, tooling, and timing together.

A GOOD ANSWER COVERS Sequence the work across multiple releases. Cycle one: announce intent, publish a migration guide on the docs site showing old versus new usage, and mark the component deprecated in docs and changelog while it still works. Cycle two: soft-deprecate in code with JSDoc deprecated tags so editors strike it through, a one-time console warning in development, and a lint rule that flags new usage. Ship a codemod, for example with jscodeshift, that rewrites the old component to the replacement automatically. Cycle three or a later major: after telemetry shows usage has dropped to a safe threshold, remove the component in a major version per semver.

COMMON WRONG ANSWERS Removing the component in a minor or patch, violating semver. Providing no codemod, leaving large codebases to migrate by hand. Warning with no replacement documented. Removing before measuring remaining usage, causing surprise breakage. Spamming warnings in production builds.

LIKELY FOLLOW-UPS How do you measure remaining usage across repos? How do you keep the codemod accurate as the replacement API evolves? How do you handle teams that cannot migrate in time? How do you avoid warning noise?

ONE CONCRETE EXAMPLE You deprecate the old Modal in favor of Dialog. v4.2 documents the migration and adds a deprecated tag plus dev warning. v4.3 ships a codemod that converts Modal props to Dialog props. Usage telemetry shows under five percent of repos still use Modal, so v5.0 removes it, with the migration guide and codemod still linked from the changelog.