A JavaScript-to-TypeScript migration does not need to be a rewrite. This practical plan shows how to introduce TypeScript in controlled stages, choose file extensions, configure tsconfig.json, prioritize risky code, and keep builds deployable while coverage grows.
Overview
The safest incremental TypeScript migration treats type coverage as a sequence of small, reviewable changes rather than a single conversion project. Keep the existing application running, establish a repeatable compiler check, and move one boundary or file group at a time.
Before changing source files, record the current baseline. Run the existing test, lint, build, and deployment commands. Note which directories contain application code, generated files, tests, scripts, configuration, and vendor code. This baseline helps distinguish migration errors from pre-existing failures.
A useful order is:
- Install TypeScript and the type packages required by your runtime and libraries.
- Add a project-specific
tsconfig.jsonwith JavaScript support enabled. - Run the compiler without emitting files and fix the most useful errors first.
- Convert stable, high-value modules from
.jsto.tsor from.jsxto.tsx. - Type module boundaries, configuration, API responses, and shared utilities.
- Increase strictness only after the team can resolve errors consistently.
The goal is not to make every line perfectly typed immediately. The goal is to make incorrect assumptions visible at boundaries where they are expensive to debug: request handling, persistence, authentication, payments, message processing, and shared state.
Checklist by scenario
Starting with a mostly JavaScript application
- Install TypeScript, the relevant runtime types, and the types for test or build tools.
- Create a separate compiler configuration if the application already has tool-specific configuration.
- Set
allowJstotrueso JavaScript and TypeScript can be checked together. - Keep
noEmitenabled when another tool owns bundling or transpilation. - Set
checkJstofalseat first if checking every JavaScript file creates an unmanageable error list. - Use
includeandexcludeto prevent dependencies, generated output, and build caches from entering the project.
A starting configuration might look like this:
{
"compilerOptions": {
"target": "ES2020",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"allowJs": true,
"checkJs": false,
"noEmit": true,
"strict": false,
"skipLibCheck": true
},
"include": ["src", "scripts"],
"exclude": ["node_modules", "dist", "coverage"]
}
These values are a migration starting point, not a universal framework recipe. Match the module and resolution settings to the project’s actual runtime and build tool. A browser application, Node.js service, and framework-managed application may require different settings.
Converting one feature at a time
- Choose a feature with a clear entry point and limited cross-module coupling.
- Convert leaf utilities before modules that import half the application.
- Rename files in small batches:
.jsto.ts, and.jsxto.tsxwhen JSX is present. - Type exported functions and objects before improving internal implementation details.
- Run tests and the type check after each logical batch.
- Keep the diff focused; avoid combining formatting, dependency replacement, and type migration in one change.
Handling an untyped or incorrectly typed dependency
First check whether the package provides types, whether a separate type package exists, and whether the import style matches the package’s documented exports. If a small internal module has no declarations, create a local declaration file rather than scattering unsafe casts:
// src/types/legacy-parser.d.ts
declare module "legacy-parser" {
export interface ParseOptions {
strict?: boolean;
}
export function parse(input: string, options?: ParseOptions): unknown;
}
Use unknown for data that still needs validation. Narrow it at the point where the application understands its shape. For external API responses, runtime validation is usually more reliable than assuming a compile-time type; see the guide to TypeScript runtime validation for patterns that separate validation from static typing.
Working in a React, Next.js, or Node.js project
Follow the framework’s existing build and test commands instead of adding a second transpilation pipeline unnecessarily. In React code, convert components and their props together when possible. In a Node.js service, begin with route handlers, service interfaces, environment configuration, and database boundaries. Keep generated clients and framework-generated files under the tool’s control; type the code that consumes them rather than editing generated output.
What to double-check
| Option or practice | Use during migration | Check before tightening |
|---|---|---|
allowJs | Includes JavaScript files in the TypeScript project. | Confirm the included files do not contain generated or unrelated scripts. |
checkJs | Reports type errors in JavaScript files, including files marked with // @ts-check. | Enable per directory or file when the team is ready to address findings. |
noEmit | Checks types without writing JavaScript output. | Keep it when a bundler, framework, or runtime transform emits files. |
declaration | Generates .d.ts files for a library or package. | Use with an explicit output directory and verify the published package exports them. |
strict | Enables a group of stronger type checks. | Adopt it in stages if existing code would produce too many unrelated errors. |
skipLibCheck | Reduces checking of declaration files in dependencies. | Do not treat it as a fix for incorrect application code or incompatible package versions. |
Also inspect module boundaries. A TypeScript migration can expose differences between default and named imports, CommonJS and ECMAScript modules, path aliases, and case-sensitive file names. Verify the command used by local development is the same command represented in CI. If the project publishes packages, review its declaration, ESM, and CommonJS output together; the TypeScript package publishing guide covers those release checks.
Prioritize files with one or more of these characteristics: they process untrusted input, have many consumers, contain complicated conditional logic, change frequently, or have caused production defects. A small utility with a stable contract may be lower risk than a large, rarely touched file. Type coverage should follow risk and dependency centrality, not just line count.
Common mistakes
Renaming the entire repository at once
A mass rename creates noisy diffs and makes failures difficult to attribute. Convert a bounded slice, preserve a working commit, and use the compiler as a progress signal.
Using any as the default migration strategy
any can unblock a narrow boundary, but it also turns off useful checking for every value that passes through it. Prefer an explicit interface for stable data, unknown for untrusted data, and a small adapter around legacy behavior. Record intentional escape hatches with comments or lint rules so they can be revisited.
Confusing declarations with runtime validation
An interface describes what the program expects; it does not inspect JSON received over HTTP or a message queue. Validate external data before using it, then infer or annotate the validated result.
Ignoring tests and editor diagnostics
The editor’s TypeScript version and the CI compiler can differ. Pin or standardize the project’s toolchain where appropriate, run the repository’s declared type-check command, and keep tests near each migration step. A green editor is not a substitute for the build that deploys the application.
Changing strictness without a plan
Strict checks often reveal real design issues, but enabling everything in one change can hide the useful signal in a large backlog. Track error categories, fix a category in a coherent area, and raise the bar as the converted surface becomes stable. For state-heavy code, discriminated unions can replace loosely related flags and make exhaustive checks practical; see the guide to TypeScript discriminated unions.
When to revisit
Revisit this migration plan before a planning cycle, after a major build-tool or framework change, and whenever a new package boundary is introduced. It is also worth reviewing after a dependency replacement, a change to the deployment target, a significant increase in type coverage, or a recurring runtime bug that static types could have caught.
Use this short review checklist:
- Run the production build, tests, lint, and the project’s type-check command from a clean checkout.
- Confirm that
include,exclude, path aliases, generated files, and declaration output still match the repository layout. - Search for new
anycasts, suppression comments, and temporary declaration files. - Check whether public APIs, environment variables, API clients, and database results have typed and runtime-validated boundaries.
- Convert the next high-risk JavaScript module only after the current batch is easy to build, test, and review.
Migration is complete when the project’s important boundaries are typed, the compiler check is part of normal delivery, and remaining JavaScript is an explicit maintenance choice rather than an untracked backlog. Keep the configuration understandable, document deliberate exceptions, and let each new feature arrive with the type coverage it would otherwise require a separate rewrite to add.