Migrating a 50K-Line JavaScript Codebase to TypeScript: Lessons Learned

We migrated a 50,000-line JavaScript codebase to TypeScript over 6 weeks — without stopping feature development. It wasn't a rewrite. It was a gradual, strategic migration that caught 47 runtime bugs that had been silently causing issues in production. Here's the exact playbook.

Phase 1: Setup without disruption (Day 1–2). Add TypeScript as a dev dependency. Create a `tsconfig.json` with `allowJs: true`, `strict: false`, and `noEmit: true` initially. This lets TypeScript coexist with your existing JavaScript. Rename your entry point to `.ts` and verify the build still works. Configure your CI pipeline to run `tsc --noEmit` — it should pass with zero errors because strict mode is off. This is your baseline.

Phase 2: Rename the safe files first (Week 1). Start with utility files, constants, and pure functions — files with no framework dependencies. Rename `.js` to `.ts`, add type annotations, and fix the errors that surface. These files are typically the easiest to type and give you quick wins. In our 50K-line codebase, we converted 120 utility files in the first week, catching 12 type coercion bugs in the process (string vs number comparisons, null access patterns).

Phase 3: Type your API layer (Week 2). Define interfaces for every API response your app consumes. Use Zod to create runtime validators that also generate TypeScript types: `type User = z.infer`. This single change catches data shape mismatches at the boundary — the #1 source of runtime errors in JavaScript apps. We found 8 API response fields that had changed upstream without anyone noticing.

Phase 4: Migrate components gradually (Week 3–4). For React apps, convert components from the bottom up — leaf components first, then containers. Add proper `Props` interfaces. Use `React.ComponentProps` to infer prop types from existing components. The key insight: don't try to make everything perfect. Use `as unknown as SomeType` escape hatches sparingly when you hit complex generic issues. Mark them with `// TODO: fix type` and move on.

Phase 5: Enable strict mode incrementally (Week 5). Turn on strict flags one at a time: `strictNullChecks` first (this catches the most bugs), then `noImplicitAny`, then `strictFunctionTypes`. Each flag will surface a wave of errors. Fix them in batches. `strictNullChecks` alone surfaced 19 potential null pointer errors in our codebase — every one of them was a real bug that could crash in production under the right conditions.

Phase 6: Lock it down (Week 6). Enable full `strict: true`. Configure ESLint with `@typescript-eslint/recommended-type-checked`. Add a pre-commit hook that runs `tsc --noEmit`. Update your CI to block merges on type errors. At this point, you have a fully typed codebase with strict guarantees. New developers can understand data flows by reading types instead of tracing runtime behavior.

The tools that made it manageable. ts-migrate (from Airbnb) for automated initial conversion of large file batches. Cursor IDE with Claude for AI-assisted type annotation — it correctly inferred types from usage patterns about 85% of the time. knip for finding dead code that didn't need to be migrated at all (we deleted 4,000 lines of unused code before migrating). Total effort: ~120 developer-hours spread across a team of 3, with zero production incidents during migration.