TypeScript Migration Checklist: 25 Essential Steps

Run `npm install -D typescript @types/node` and any framework-specific type packages (`@types/react`, `@types/express`, etc.). Pin the TypeScript version in package.json to avoid surprise breakages when a new release changes type inference behavior.

Run `npx tsc --init` and start with `strict: false`, `allowJs: true`, and `checkJs: false`. This lets you rename files to .ts/.tsx without immediately fixing every type error. You'll tighten these settings as the migration progresses.

Set `baseUrl` and `paths` in tsconfig.json to mirror any existing webpack or babel aliases (e.g., `@/` mapping to `src/`). Mismatched aliases cause import resolution failures that look like missing module errors.

Choose `target` based on your minimum supported environment (e.g., `ES2020` for Node 14+, `ES2022` for modern browsers). Set `module` to match your bundler — `ESNext` for Vite/webpack, `NodeNext` for Node.js ESM projects. Wrong settings cause subtle runtime bugs.

Update your build scripts to run `tsc --noEmit` for type checking (let your bundler handle transpilation). Add a `typecheck` npm script and integrate it into your CI pipeline so type errors block PRs from the start.

Rename pure utility files (helpers, constants, config) from .js to .ts first. These typically have simple types and few dependencies, giving your team quick wins and building confidence with the TypeScript workflow.

Create a `types/` directory and define interfaces for your core domain objects (User, Product, APIResponse, etc.). Having shared types ready before converting components means you won't need `any` as a placeholder for common shapes.

Convert files that have no internal imports first (leaf nodes in your dependency graph), then work inward. This avoids cascading type errors from unconverted dependencies. Use a tool like `madge` to visualize your dependency graph.

Create `.d.ts` files for JavaScript modules you haven't converted yet. Even a simple `declare module './legacy-module'` prevents import errors. Add basic type signatures as you learn how each module is actually used.

When you convert `utils.js` to `utils.ts`, convert `utils.test.js` to `utils.test.ts` at the same time. Tests are the fastest way to validate that your type annotations match actual runtime behavior.

Instead of `(value as User)`, write a type guard function like `function isUser(val: unknown): val is User`. Type assertions silence the compiler; type guards actually validate at runtime and narrow types safely.

Type API responses, JSON.parse results, and user input as `unknown` instead of `any`. This forces you to validate the shape before using it, catching malformed data at the boundary instead of deep in your business logic.

Model states like `{ status: 'loading' } | { status: 'success'; data: T } | { status: 'error'; error: Error }` instead of `{ loading: boolean; data?: T; error?: Error }`. Discriminated unions make impossible states unrepresentable.

Explicitly annotate return types on all exported functions. This catches accidental return type changes and provides better error messages at the function definition rather than at distant call sites.

Add `as const` to configuration objects, route maps, and enum-like arrays. Without it, TypeScript widens `['admin', 'user']` to `string[]`, losing the ability to narrow on specific values in switch statements and conditionals.

This flag forces you to annotate parameters and variables that TypeScript can't infer. It's the single highest-value strict flag because implicit `any` silently disables type checking for everything it touches.

This flag makes `null` and `undefined` their own types instead of assignable to everything. It catches the most common runtime error in JavaScript — accessing properties on null/undefined — at compile time. Expect many errors initially.

This flag enforces contravariant parameter types in function assignments, catching subtle bugs where a callback expecting a specific type gets assigned a handler that assumes a broader type. It's usually low-friction to enable.

Array and object index access returns `T | undefined` instead of just `T`. This catches bugs like `items[0].name` when the array might be empty. It adds verbosity but prevents real production crashes.

After enabling each strict flag one at a time, replace them all with `strict: true`. This ensures future TypeScript releases that add new strict checks are automatically applied. Document the migration date so the team knows when strict was achieved.

Search your codebase for `: any` and `as any`. Each one is a type-checking escape hatch that defeats the purpose of TypeScript. Replace with proper types, `unknown`, or generics. Track your `any` count as a migration metric.

These suppression comments were useful during migration but should not remain in the final codebase. Each one hides a real type problem. Fix the underlying issue or, if truly necessary, document exactly why the suppression exists.

Run a find command to check for any unconverted JavaScript files. Stray .js files bypass type checking and can reintroduce untyped code paths. Exclude vendored files and generated output from this check.

Install `@typescript-eslint/eslint-plugin` and enable rules like `no-explicit-any`, `no-non-null-assertion`, and `strict-boolean-expressions`. Linting prevents type safety regressions after the migration is complete.

Ensure your CI pipeline runs `tsc --noEmit` and blocks merges on type errors. Add a lint rule or CI check that rejects new .js files in the src/ directory. This protects the migration investment from gradual erosion.