TypeScript Migration Guide for Growing Codebases

Every founder who runs a growing JavaScript codebase eventually faces the TypeScript migration question. The team keeps hitting bugs that types would have caught. Onboarding new engineers takes longer because the codebase requires reading rather than trusting signatures. Refactoring is scary because there is no compiler to catch broken references. The pain is real and it compounds. But full migration also feels like a project the team cannot afford because features cannot pause. This guide is the working migration strategy we use inside QwiklyLaunch 45-day sprints when a client asks us to modernize a JavaScript codebase. It is designed to migrate incrementally without stopping feature work, with clear phases and measurable progress. Follow it and you will have a fully typed codebase within two to six months depending on size, without ever stopping product development.

The Argument for Migrating Now

Every quarter you delay TypeScript migration, the migration gets harder. Codebases grow. New JavaScript accumulates alongside the old. The final effort scales with total lines of code. Migrating today when you have 40000 lines is far easier than migrating in a year with 90000 lines. Delaying also compounds bug cost. Types would have caught many of the bugs your team shipped last quarter. Those bugs cost real hours in triage, hotfix, and customer support. Migration is not a nice-to-have. It is a productivity investment with measurable payback within six months for most teams.

Signals that you should migrate now

• Refactoring feels dangerous because of unknown callers
• New developer onboarding takes over two weeks
• Runtime type errors show up regularly in production
• Autocomplete in your IDE is unhelpful
• Code review discussions frequently ask about data shapes

Phase 1: Add TypeScript Alongside JavaScript

The first phase adds TypeScript to the project without touching existing JavaScript files. Install typescript, add a tsconfig.json with allowJs true and checkJs false, and configure your build to handle both file extensions. New files can be written in TypeScript from day one. Existing JavaScript files stay JavaScript. This phase should take one to three days depending on build tool complexity. The goal is proving TypeScript works in your project without disrupting anything. Every new file after this phase should be TypeScript by default.

Phase 2: Type the Boundaries First

Boundaries are where data enters or leaves your system. API responses, database queries, form inputs, and external library calls are all boundaries. Type these first because untyped boundaries poison every downstream function. Use Zod or Valibot for runtime validation with automatic type inference. Every API endpoint should have a typed response schema. Every database query should return typed rows. Every form should validate with a schema. Typing boundaries gives you the biggest correctness win for the least effort.

Boundary types to add first

1. API request and response schemas
2. Database row types from your ORM
3. Form input schemas and validation
4. Third-party library return types
5. Environment variable types

Phase 3: Convert File by File

Rename JavaScript files to TypeScript one at a time. Start with the smallest and most stable files. Add types as you go. Use any as a placeholder where inference fails, marked with a comment for later cleanup. This is not the ideal end state but it lets you convert quickly without blocking on hard cases. Track conversion progress in a simple spreadsheet. Aim for 5 to 10 files per week per engineer. At that pace, a 200-file codebase converts in 4 to 10 weeks. This work fits naturally alongside feature development.

Phase 4: Enable Strict Mode Gradually

tsconfig strict mode is the goal. Enable it flag by flag rather than all at once. Turn on noImplicitAny first. Fix everything it flags. Then strictNullChecks. Fix everything. Continue through the other strict flags one at a time. Each flag reveals a category of unsafe code. Fixing incrementally is manageable. Enabling all strict flags at once produces thousands of errors and paralyzes the team. This phased approach is what makes strict TypeScript feasible on real codebases with real deadlines.

Strict flag order for gradual adoption

• noImplicitAny first, easiest to fix
• strictNullChecks second, catches most bugs
• strictFunctionTypes and strictBindCallApply together
• strictPropertyInitialization for classes
• noImplicitThis and alwaysStrict finish the set

Tooling That Accelerates Migration

Several tools speed up conversion. ts-migrate from Airbnb converts JavaScript to TypeScript with reasonable inference. TypeScript's own JSDoc support lets you add types via comments before converting files. Automated codemods from libraries like jscodeshift handle common patterns. Copilot and other AI tools are excellent at inferring types from JavaScript context. Use tools where they help but review every generated type. Bad automated types are worse than no types because they lie to future developers.

Handling Third Party Libraries

Most modern libraries ship with TypeScript types. Older libraries may not. Check the DefinitelyTyped repository for community types before writing your own. When a library has no types, create a simple declaration file with the types you use. Do not attempt to type the entire library. Type only the surface area your code touches. This pragmatic approach avoids weeks of unnecessary work on libraries you barely use. Documented in our web development engagements as a repeatable pattern.

Common Migration Mistakes

Teams make predictable mistakes during migration. Trying to type everything at once produces burnout and stalled progress. Using any everywhere defeats the purpose of migration. Skipping the boundary phase means every downstream function has weak types. Ignoring strict mode leaves you with types that lie. Not enforcing TypeScript for new files means the untyped code keeps growing. Avoid these mistakes by following the phased approach with clear conventions enforced in code review.

Keeping Feature Work Going

Migration must happen alongside feature work. The pattern that works is 20 percent of engineering time on migration for the first three to six months. That means each engineer spends about one day per week on conversion. Track migration progress in your sprint reviews alongside feature progress. This proportion is small enough to not slow features noticeably and large enough to make steady progress. Founders who try to migrate in a dedicated sprint always fail because pressure to ship features returns and migration stalls.

Measuring Migration Progress

Track three metrics weekly. Percentage of files in TypeScript. Percentage of the codebase covered by strict mode. Number of any types remaining. All three should trend in the right direction each week. When any of them stalls, discuss the blocker in your engineering sync and adjust. Publishing the metrics keeps migration visible and prevents it from silently deprioritized. This visibility is what separates migrations that finish from migrations that stall at 60 percent forever.

The Post Migration Payoff

Teams that complete TypeScript migration report specific benefits. Refactoring becomes safe because the compiler catches broken references. New developer onboarding drops from weeks to days because types document the codebase. Runtime type errors drop by 60 to 90 percent. IDE autocomplete becomes reliable. Code review discussions focus on logic rather than shape questions. These benefits compound over years. Every quarter of well-typed code produces value in every future quarter.

Discriminated Unions for State Modeling

TypeScript discriminated unions let you model state precisely. A loading state, an error state, and a success state can each carry only the data relevant to that state. This eliminates entire classes of bugs where components try to render error data during loading or vice versa. Use a common tag field like status to discriminate. Combine with type narrowing to let the compiler enforce that only valid state combinations exist. Teams that adopt this pattern report cleaner components and fewer defensive null checks throughout the codebase.

State pattern example

• Loading: has status loading, no data, no error
• Success: has status success, has data, no error
• Error: has status error, has error message, no data
• Idle: has status idle, no data, no error

Generics for Reusable Utilities

Generics enable type-safe reusable code. Instead of writing separate typed utilities for each shape, one generic utility works across all shapes. This reduces code duplication and improves type safety. Do not overuse generics though. Deep generic types become hard to read and maintain. When a utility would need three or more type parameters or complex conditional types, consider whether a specialized version would be clearer. Balance abstraction against readability.

Testing TypeScript Types

Types themselves can have bugs. Test them with tools like tsd or expect-type. Verify that expected inputs produce expected types and that invalid inputs fail compilation. This is especially important for library code and shared utilities used across the codebase. Type tests are fast, run during regular tsc compilation, and catch regressions that runtime tests would miss. Include type tests in your CI pipeline alongside unit and integration tests.

Handling Legacy JSDoc Comments

Some codebases already use JSDoc comments for type documentation. TypeScript can read JSDoc types with the checkJs option, giving you type checking without renaming files. This is a useful intermediate step during migration. Use JSDoc types as a bridge, then convert files to TypeScript when the team is ready. Do not maintain JSDoc types long-term because they diverge from actual TypeScript types and produce confusing edge cases. The bridge is temporary. Plan the conversion timeline explicitly rather than leaving JSDoc as the permanent solution.

Configuring TSConfig for Real Projects

The tsconfig.json is where most projects underinvest. Beyond strict mode, enable useUnknownInCatchVariables to prevent unsafe error handling. Enable noPropertyAccessFromIndexSignature to force explicit index signature access. Configure paths for cleaner imports without breaking build tooling. Set incremental to true for faster builds. Set tsBuildInfoFile to a stable location for incremental cache. These small settings compound into significantly better developer experience across large projects.

tsconfig settings that pay off

1. strict true with all sub-flags enabled
2. useUnknownInCatchVariables for safer catch blocks
3. noPropertyAccessFromIndexSignature for explicit dynamic access
4. exactOptionalPropertyTypes for stricter optional handling
5. paths for cleaner cross-directory imports

Working With TypeScript in Monorepos

Monorepos have specific TypeScript concerns. Project references let you build packages independently while sharing types. Turborepo, Nx, and pnpm workspaces all handle this well with proper configuration. Set up path aliases at the root so packages import each other with clean paths. Avoid deep cross-package imports that create tight coupling. Package boundaries are architectural boundaries. Enforce them with linting rules that prevent unauthorized imports. This discipline prevents monorepos from degenerating into one giant package with no real modularity.

Type-Safe Environment Variables

Environment variables are strings from the shell but code often expects specific types. Use a schema library like Zod or Envalid to validate and type environment variables at boot. This catches misconfiguration immediately with clear error messages instead of confusing runtime failures deep in the app. Every project should have a single env module that exports typed environment values. Never read process.env directly in application code. This pattern prevents entire categories of production incidents caused by misconfigured environments.

Handling Third-Party Library Type Issues

Some third-party libraries ship with weak or incorrect types. Options include using module augmentation to fix types locally, contributing fixes upstream to the library, or writing custom wrappers that expose corrected types. Never suppress type errors with any across large surface areas. That defeats the purpose of migration and introduces silent bugs. When you must suppress an error, use a specific ts-expect-error with a comment explaining why. Then track these suppressions as technical debt to remove later. Publish the count as a migration metric.

Type-Driven Refactoring

Once your codebase is well typed, refactoring becomes safe. The compiler tells you every file that needs to update when you change a type. This enables large refactors that would be terrifying in an untyped codebase. Use this capability regularly. Rename fields, restructure APIs, and consolidate patterns without fear. Teams that refactor confidently ship features faster than teams that avoid refactoring due to fear of breakage. Migration to TypeScript is what makes this speed possible over the long term. Teams often report that the biggest surprise after finishing migration is not the reduced bug count but the increased willingness to refactor. That willingness compounds into cleaner architecture every quarter and reduces long-term maintenance cost significantly across large codebases. The compounding benefit is what makes the initial migration investment worthwhile even for teams that resist it initially before seeing the payoff firsthand in real production code across many quarters of active development work.

Communicating Migration Progress to Stakeholders

Founders and non-technical stakeholders need to see migration progress in terms they understand. Convert the three engineering metrics into business language. Instead of percentage of files migrated, report percentage of the codebase now protected by types. Instead of any count, report categories of bugs now impossible. Instead of strict flag coverage, report increased velocity from safer refactoring. This translation keeps stakeholders supportive of the ongoing investment and prevents pressure to abandon migration before it delivers full value.

How This Fits a 45-Day Sprint

Inside a QwiklyLaunch 45-day sprint, we sometimes deliver TypeScript migration as a scoped deliverable alongside new features. The pattern is the same: type boundaries first, convert file by file, enable strict flags gradually. In 45 days a small team can typically migrate 100 to 300 files while shipping new work. Larger codebases take longer, but the phased approach means visible progress every week. Read related engineering discipline posts on the blog for more context.

TypeScript migration is not glamorous but the payoff is enormous. Codebases that migrate stay productive for years. Codebases that stall on JavaScript accumulate bugs and slow down. The migration is manageable when done in phases without stopping feature work. If you want a team that has migrated JavaScript codebases of all sizes, start a conversation with our team. You can also see how we structure engineering work on the projects page.