You own a large, actively developed JavaScript codebase and the team wants type safety. How would you decide between an incremental TypeScript migration, a rewrite in TypeScript, and staying on JavaScript with types checked by tsc?

## Frame the decision, not the technology The question is never "is TypeScript good". It is: what buys the most defect reduction per engineer-week, given this codebase, this team, and this roadmap. Three options are on the table, and the judgment being assessed is whether you can price each one honestly. ## Option one: rewrite A rewrite is the option that feels fastest and almost never is. Its costs are structural. You fork: two codebases now exist, and every bug fix and feature has to be applied twice or held until the switch. You lose the encoded history — the odd branch that handles a specific customer's malformed input, the workaround for a browser quirk — which looks like cruft to a rewriter and is regression bait. And you have no incremental value: nothing ships until it all ships, so the project is uniquely vulnerable to a change in priorities halfway through. It is defensible in a narrow case: a small, well-bounded module with strong test coverage and stable requirements, especially one you were going to rework anyway. Then "rewrite" is really "convert with an implementation change", and the tests carry the risk. ## Option two: incremental migration This is the default for a reason. The compiler accepts both extensions in one program, so the codebase is always in a shippable state, and conversion proceeds file by file with each step small enough to review and revert. Value arrives continuously: the first converted modules start catching bugs while the rest of the tree is untouched. The honest costs are a long tail and a visibly mixed codebase. Mid-migration, a reader has to know which conventions apply where, and a half-strict configuration gives weaker guarantees than either end state. Momentum is the real risk: without a ratchet in CI and named ownership, migrations stall at seventy percent and stay there for years. The inputs that argue for it: an existing build step, a codebase that will live for years, decent test coverage, and a team that will keep touching the same files anyway. ## Option three: type the JavaScript in place Often underrated. The compiler can check JavaScript sources directly, with types expressed in comment syntax, and no file is renamed. You get the same checker, the same errors, the same editor support — with the disruption of a migration removed. This wins outright in specific situations: there is no compile step and adding one is a bigger change than the typing itself; the package ships as source and consumers run it directly; the code is short-lived; or the organisation cannot absorb a change that touches every file. Its costs are real but bounded: the syntax is verbose, a few type-level constructs are awkward to express, and hiring or onboarding assumes the mainstream form. It is also a legitimate *stage*: type in place first, prove the value with real defects caught, then rename later if the case is made. That sequencing lets you decide with evidence instead of conviction. ## The decision inputs - **Is there already a build step?** If yes, incremental migration is nearly free to start. If not, the honest comparison is against typing in place. - **How is it distributed?** A library that ships source, or code executed directly by a runtime, tilts toward typing in place. - **Test coverage.** Coverage is what makes conversion edits safe; without it, every migration commit is unverified. - **Churn.** High-churn files are painful to convert (merge conflicts) but pay back most, since they are edited constantly. Dead-quiet code pays back least — and code scheduled for deletion pays back nothing. - **Team appetite and skill.** A migration that the team does not believe in stalls, and a stalled migration is worse than none: you carry the mixed-codebase cost without reaching the benefit. - **Time horizon.** Under a year of remaining life, the payback usually is not there. ## Define done before you start The most common failure is not choosing wrong; it is never declaring an end state. Write it down: full strict everywhere, or strict in the product tree with two legacy directories excluded until they are deleted, or typed-in-place indefinitely. Then put a ratchet behind it — a CI gate that stops new untyped files appearing and holds the outstanding-error count so it can only fall — and assign the remaining work by directory to the teams that own it. ## Measure it Defend the choice with numbers rather than taste: the share of the codebase under checking, the outstanding error count trending down, and the classes of production incident that types would have prevented. If a quarter of migration effort has not moved any of those, that is evidence to change strategy — including to stop where you are and call the mixed state the answer.