Migrating a JavaScript Codebase to TypeScript Without Blowing Up the Roadmap

The JavaScript-to-TypeScript migration is one of those projects every mid-stage team eventually runs. It's rarely urgent, always beneficial, and almost always underestimated. Done badly, it eats a quarter of engineering time for a year. Done well, it happens in the background while the team keeps shipping.

Migrating a JavaScript codebase to TypeScript isn't a rewrite. It's a gradual shift with concrete milestones. This post is the sequence we've seen work when a team decides to make the move.

Why teams migrate

Three real benefits, in order of impact.

Refactoring becomes safe

Types catch the "you forgot to update this call site" mistake automatically. Refactoring a widely-used function goes from a scary multi-day project to a compiler-guided afternoon.

Onboarding gets faster

New engineers read types instead of function bodies to understand what code does. On a large codebase, this cuts onboarding time significantly.

Editor tooling gets good

Autocomplete, inline docs, jump-to-definition — all work better with types. This isn't just a productivity boost; it's a reduction in the mental tax of reading code all day.

When migration is worth it

Not every JS codebase should migrate. Some are too small for the effort to pay back. Some are too near end-of-life to justify the investment. Some are so tangled that the migration turns into a rewrite anyway.

The signals that migration is worth it:

• More than a few thousand lines of active code.
• More than one engineer working on it.
• Regular feature work over the next year or more.
• New engineers joining regularly.

Miss all four and TypeScript is a nice-to-have. Hit two or more and the migration probably pays back.

The incremental approach

The single biggest reason migrations fail is trying to convert everything at once. The teams that succeed do it file by file, over months, while continuing to ship features.

Step 1: install TypeScript alongside JavaScript

Add TypeScript as a dev dependency. Configure tsconfig.json with allowJs: true so JavaScript files still compile. Both languages coexist. Nothing breaks.

This step alone takes a couple of hours. Nothing in production changes.

Step 2: rename one file to .ts

Pick a small, isolated file. Rename it, fix the type errors, ship it. You've now proven the setup works in production.

Do this before writing any migration plan. The tooling either works with your build system or it doesn't; better to know on day one.

Step 3: enable strict mode gradually

TypeScript's strict mode has multiple flags. Enable them one at a time, fixing errors as you go. noImplicitAny first, then strictNullChecks, then the rest.

Enabling all of strict at once produces thousands of errors and gets abandoned. One flag at a time produces manageable fix lists.

Step 4: convert files as you touch them

Every feature or bug fix that touches a JS file, convert that file to TS. Over months, the important files get converted naturally. The unused files stay JS forever, which is fine — they weren't hurting anyone.

This is the pattern that works. It ties migration effort to real work. Files that matter get converted; files that don't stay untouched.

Step 5: schedule the last mile

After 80% of the code is converted through natural attrition, schedule a focused sprint to convert the remaining files. This is the only "dedicated migration effort" the team does, and it's short.

Tools that help

A few tools are worth knowing about.

ts-migrate

Airbnb's tool for bulk conversion. Runs across your codebase, converts .js to .ts, and adds "any" types where inference fails. Good starting point for large migrations; the "any" types become a to-do list.

typescript-eslint

Lets you enforce TypeScript-friendly patterns in JavaScript files. Great for teams that want to gradually raise standards before full migration.

Zod or valibot

For the "our data is validated at runtime but not typed" problem. Schema libraries generate types from validation code, so you get both at once. Useful for API boundaries and form validation.

Mistakes teams make

Treating migration as a project. "Q3 is the TypeScript quarter." Nobody hires you to migrate; they hire you to ship. Migrations that pause feature work usually get canceled halfway through.

Insisting on zero "any" types from day one. Perfect types are the enemy of good types. Start with "any" where inference fails, tighten later.

Configuring TypeScript strictly at the outset. Ambitious tsconfig files produce thousands of errors and demoralize the team. Start loose, tighten gradually.

Migrating dead code. Files nobody uses don't need types. Delete them, or leave them as .js forever.

Timelines to expect

Rough numbers from projects we've helped with.

• Under 10,000 lines: 4-8 weeks calendar, done alongside feature work.
• 10,000 to 50,000 lines: 3-6 months calendar.
• 50,000+ lines: 6-12 months, with a final sprint to close out.

Half the effort is fixing the type errors themselves. The other half is adjusting build tooling, adding types for third-party libraries that don't ship them, and cleaning up patterns that worked in JS but don't in TS.

Third-party libraries

Most modern libraries ship their own TypeScript types. Older libraries may not. Three patterns for handling them.

DefinitelyTyped

Community-maintained types at @types/library-name. Install and it works. First place to look.

Ambient declaration files

For libraries without types, write a small .d.ts file declaring the module. Not fun but not hard. Ships with your code.

The escape hatch

declare module "some-library" with an "any" type. Ugly but shippable when a library resists typing. Add a TODO to revisit.

Trade-offs

Types cost something. Every prop, every function signature, every generic is time spent. In small codebases with clear intent, that time isn't earned back. In large codebases with multiple contributors, it's earned back several times over.

TypeScript can also over-abstract. Teams new to types often build elaborate generic gymnastics that make the code harder to read than the JS it replaced. Start with simple types; add complexity only when there's a reason.

Common misconceptions

"TypeScript slows us down." It slows down writing throwaway code and speeds up maintaining shipped code. If the codebase has real users, the trade-off favors TS.

"We need to migrate everything before we get value." Not true. Every file converted immediately gives editor-tooling and refactor safety on that file. Value compounds; it doesn't wait until the end.

"We can use JSDoc instead." You can, and for very small codebases it's fine. Beyond a certain size, JSDoc types get unwieldy compared to real TS. Most teams that start with JSDoc migrate to TS eventually.

Frequently asked questions

Final take

The best migration is invisible. Files get converted as work touches them, the team keeps shipping, and one day someone notices the codebase is 90% TypeScript without any dedicated migration effort. That's the version worth aiming for.

If you're planning a TS migration and want a review of the setup, tooling, or timeline before you commit, book a call. We've helped teams your size run this well.