Migrating a Large JavaScript Codebase to TypeScript
You can migrate a large JavaScript codebase to TypeScript without stopping feature development. It isn’t a rewrite. It’s a gradual migration, one batch of files at a time, and along the way it surfaces runtime bugs that have been quietly causing problems in production. Here’s the 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. This first batch often surfaces type coercion bugs that were already in production (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<typeof userSchema>`. This single change catches data shape mismatches at the boundary — a common source of runtime errors in JavaScript apps. This is also where you find API response fields that 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<typeof Component>` 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. Expect `strictNullChecks` to surface the largest batch: each error is a place where a missing value can crash the app 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 make it manageable. ts-migrate (from Airbnb) for automated initial conversion of large file batches. An AI coding assistant such as Cursor for suggested type annotations, which you still review by hand. knip for finding dead code that doesn’t need to be migrated at all: delete it first and the migration gets smaller. Run the type check in CI from the first day, so the migration never blocks a release.
Building AI-heavy SaaS products, running a digital agency, and sharing everything I learn along the way.
Ready to build something extraordinary?
Book a free 30-minute strategy call. No pitch decks, no fluff — just a clear plan for your project.
