You lead a large React codebase where most screens are exported through chains of legacy `withX` higher-order components. How do you plan the move to hooks without a freeze-and-rewrite?

## First, justify the work A migration with no cost argument gets abandoned halfway, which is worse than not starting: you end up maintaining both idioms with no end date. So state the cost in terms someone outside the team recognises. Usually it is one of: incident response is slow because finding which wrapper owns a piece of state takes minutes; onboarding is slow because a component's props have no visible origin; a class of silent bugs recurs because stacked wrappers collide on prop names. "Hooks are more modern" is not a cost argument, and a reviewer will say so. ## Inventory before you touch anything List every `withX` in the codebase with three facts: how many call sites, how deep it typically stacks, and what it injects. That inventory does most of the prioritisation for you. A wrapper used twice and never stacked is not worth a migration; a wrapper on 200 screens that always appears inside two others is the one paying for the project. Classify each one as: *pure logic* (computes and injects props — fully convertible), *renders something* (a provider, a layout element, a gate that may render a fallback — stays a component), or *third-party adapter* (wraps a component you do not control — usually stays). ## The bridge that makes it incremental The single most useful technique is to invert the implementation rather than replace it. Take the wrapper's logic out into a hook, then rewrite the wrapper in terms of the hook: ```jsx export function useCurrentUser() { // the logic that used to live inside withCurrentUser } export function withCurrentUser(Wrapped) { function WithCurrentUser(props) { const user = useCurrentUser(); return <Wrapped {...props} user={user} />; } WithCurrentUser.displayName = `withCurrentUser(${Wrapped.name || 'Component'})`; return WithCurrentUser; } ``` Now both surfaces exist, backed by one implementation. Existing call sites keep working untouched; new code imports the hook. The dangerous edit — moving the actual logic — happens once, in a small diff, covered by whatever tests already exercised the wrapper. Everything after that is mechanical and independently revertible. ## Sequencing Convert call sites leaf-first: change the component to call the hook, delete the wrapper from its export, adjust the props it no longer receives. Do it in batches that match review capacity, and prefer batches that fully retire one wrapper over batches that half-retire five, because a wrapper you can delete is progress you can see. Be wary of codemods here. The transformation is not purely syntactic: the injected prop may be renamed, may be optional, may be threaded further down to children, and may be typed loosely. A codemod that gets 90% right leaves a 10% tail that is harder to find than if you had done it by hand. Codemods are reasonable for the mechanical half (rewriting the export, removing the wrapper) with human review of the props. ## Guardrails Stop the bleeding first: agree that new code uses the hook, and enforce it however your repo enforces conventions — a lint restriction on importing the wrapper, a review checklist, or simply not exporting the wrapper from the package's public entry point. A migration that competes with ongoing creation of new usages never converges. Pick one metric and publish it. Wrapper depth on your ten busiest screens is concrete and moves visibly. Number of remaining call sites per wrapper works too. Avoid metrics you cannot move directly, like bundle size, which will be dominated by other factors. ## Know what you are keeping Declare the residue explicitly, or people will keep filing tickets about it: - Error boundaries remain classes, because catching render errors requires one. - Wrappers that render a provider, a layout element, or a fallback stay components — a hook cannot render. - Adapters around third-party components you cannot modify stay. - Anything with two call sites and no pain stays until it is touched for another reason. ## The failure modes to name Two migrations go wrong predictably. The first stalls at 60% and leaves both idioms permanently, because no one owned the tail — fix by scheduling the tail as work, not as opportunistic cleanup. The second breaks production because a wrapper was doing something undocumented — an implicit default prop, an ordering dependency between two wrappers, a side effect at module scope. That is why the bridge step matters: it lets you move the logic while the composition still holds, so surprises surface one at a time instead of all at once.