JavaScript to TypeScript Migration Checklist: A Step-by-Step Plan for Safer Refactoring

Overview

Moving an existing JavaScript codebase to TypeScript changes more than file extensions. It introduces a compilation step, new project conventions, type definitions for application boundaries, and a feedback loop based on compiler errors. The migration plan should therefore protect working behavior while gradually increasing the amount of code checked by TypeScript.

A practical migration usually has four stages:

1. Prepare the project: establish a repeatable TypeScript configuration, scripts, and baseline checks.
2. Convert low-risk code: start with utilities, constants, and well-tested modules before high-change application boundaries.
3. Improve type coverage: replace temporary escape hatches, type shared models, and enable stricter checks in stages.
4. Make the result durable: update builds, tests, linting, documentation, and ownership rules so new JavaScript does not quietly return.

Before making changes, record a baseline: the commands used to install dependencies, run tests, lint files, build the application, and start local development. Keep that baseline available throughout the migration. If a check fails later, you can distinguish a pre-existing issue from a regression caused by the conversion.

For compiler configuration decisions, use a focused reference such as the complete tsconfig.json guide or the guide to essential TypeScript compiler options. The right configuration depends on whether the project is a browser application, Node.js service, package, or monorepo.

Checklist by scenario

Before converting the first file

• Inventory source directories, test directories, generated files, scripts, and configuration files.
• Identify the runtime and module system used by the application.
• Confirm how code is bundled, executed, tested, and deployed.
• Install TypeScript and the type-aware tooling required by the project.
• Create a tsconfig.json with an explicit root, output behavior, module settings, and included files.
• Decide whether JavaScript files will remain temporarily included with options such as allowJs and checkJs.
• Add a dedicated type-check command, such as tsc --noEmit, without replacing the existing build command prematurely.
• Record the initial number and location of known type errors.
• Agree on where temporary declarations, shared types, and migration notes will live.

When the codebase is mostly application logic

Convert stable, low-dependency modules first. Formatting helpers, constants, pure functions, and small domain utilities usually expose fewer integration problems than entry points or framework configuration. Preserve behavior during the first pass; avoid redesigning the module at the same time.

• Rename one small group of .js files to .ts, or .jsx files to .tsx.
• Fix syntax and import issues created by the new compilation step.
• Add types to exported function parameters and return values first.
• Type object shapes that cross module boundaries instead of annotating every local variable.
• Run focused tests after each logical group of changes.
• Commit conversions in reviewable units so they can be reverted independently.

Do not begin by typing every implementation detail. A useful first milestone is that public interfaces are understandable and incorrect calls are detected. You can refine internal types after the module is stable.

When migrating React or another frontend application

• Convert shared data models and utility modules before large components.
• Rename JSX-containing files to .tsx and address event, ref, children, and component-prop types deliberately.
• Type network responses at the boundary rather than assuming that parsed JSON is trustworthy.
• Check form values, route parameters, environment variables, and state initialized from empty or partial data.
• Keep runtime validation separate from compile-time types when data comes from users, APIs, or storage.

For forms, the React Hook Form, Zod, and TypeScript guide provides a useful example of combining static types with runtime validation.

When migrating a Node.js or backend project

• Decide whether TypeScript will compile to a build directory or be executed through a development-time runner.
• Keep the production command explicit about which output is deployed.
• Type request parameters, parsed bodies, database results, and service return values at their boundaries.
• Handle errors as an unknown value until the code has established what it contains.
• Type configuration loaded from the environment and validate required values during startup.
• Test the compiled output when deployment runs compiled JavaScript.

Backend projects often expose weak assumptions through external inputs. A successful compilation does not prove that a request body, database row, or environment variable has the expected runtime shape.

When third-party packages create the most friction

• Check whether the package includes its own declarations.
• Look for a compatible community type package where appropriate.
• Wrap an untyped dependency behind a small local module instead of spreading any across the application.
• Document temporary declarations and assign an owner to replace them later.
• Verify import style and module settings before changing package code or compiler settings.

A declaration file can be a useful bridge, but it should describe verified behavior rather than simply silence an error. Treat broad declarations as migration debt with a visible follow-up task.

What to double-check

Strictness rollout

Strict mode is valuable, but enabling every check at the start can produce a large, poorly prioritized queue. If the codebase is large, introduce strictness in stages and track which option is responsible for each remaining category of work. Avoid permanently weakening the configuration just to make a conversion appear complete.

Pay particular attention to nullable values, implicit any, unchecked indexed access, and function parameters. These areas often reveal assumptions that were previously hidden. When a value may be absent, model that possibility and narrow it before use. See the guide to type narrowing and common compiler errors for practical patterns.

Shared models and boundaries

Review types used by multiple layers: API responses, database records, events, configuration, authentication results, and reusable component props. Decide whether each type represents input, validated data, persistence, or output. Similar-looking objects are not always interchangeable, and naming the boundary helps prevent accidental coupling.

Use utility types carefully when a relationship is genuinely structural. For example, a partial update type may be appropriate for a patch operation, while a create-input type should not automatically include generated identifiers. The mapped types guide can help when reusable transformations are justified.

Build, tests, and linting

• Run type-checking in continuous integration, not only in an editor.
• Confirm that tests compile and execute under the same module assumptions as the application.
• Check source maps and stack traces in the development and production workflows.
• Update linting to parse TypeScript and agree on rules for unused variables, explicit types, unsafe values, and imports.
• Ensure generated files and dependencies are excluded from the intended type-check scope.
• Test packaging and deployment from a clean installation.

If compilation becomes slow as the project grows, consider whether project references or a different build arrangement would improve boundaries. The project references guide is relevant for larger multi-package repositories.

Common mistakes

• Converting everything in one branch: A large migration is difficult to review and difficult to bisect. Prefer small batches with passing behavior checks.
• Using any as the final design: Temporary escape hatches are sometimes practical, but mark them and measure their removal.
• Typing external data as if it were validated: A TypeScript annotation does not validate JSON, user input, or environment values at runtime.
• Changing architecture during conversion: Separate mechanical migration from redesign unless the existing structure prevents compilation.
• Ignoring JavaScript files left behind: Define which extensions are allowed and add a review or lint rule to prevent unplanned growth.
• Relying only on editor feedback: Editors may use a different configuration from CI or the production build. Make the authoritative commands easy to run locally.
• Hiding errors with broad declarations: A declaration that says everything is valid can remove the very feedback the migration is intended to create.

When an error is confusing, isolate the smallest reproducible case before changing compiler settings. For common assignment problems, consult the guide to “string is not assignable to type” errors. For name collisions introduced by new declarations, review the guidance on duplicate identifier errors.

When to revisit

Revisit this checklist before a planned refactoring cycle, after a major framework or build-tool change, and whenever the project adds a new package, runtime, or deployment target. The migration is not finished merely because all files use a .ts extension; it is finished when type-checking, tests, linting, and deployment describe the same reliable workflow.

At each review, check the following:

1. Are new JavaScript files being added intentionally?
2. Has the count of temporary any values, ignores, and ambient declarations changed?
3. Do shared models still match actual API, database, and event payloads?
4. Do local and continuous-integration commands use the intended tsconfig?
5. Does the build still produce the files and module format expected by deployment?
6. Have updated dependencies changed available type definitions or import behavior?
7. Can a new contributor follow the migration conventions without relying on tribal knowledge?

Keep a short migration log with completed areas, known exceptions, and the next smallest useful task. That record turns a one-time conversion into an ongoing TypeScript best practice: type boundaries first, preserve behavior, verify continuously, and improve strictness as the codebase becomes easier to understand.