TypeScript Reference ยท Concepts and Comparisons
Migrating a JavaScript project to TypeScript
A practical order of work for moving a JavaScript codebase to TypeScript: allowJs, checkJs, JSDoc, renaming files, strict flags and where to stop.
You do not have to convert a JavaScript codebase in one go. TypeScript can check JavaScript files, accept them alongside .ts files, and tighten its rules one flag at a time. The safest migrations are boring: many small steps, each one merged while the application keeps working.
A good plan has three phases. First, make the compiler run over the project without changing behavior. Second, convert files from the leaves of the dependency graph upward. Third, turn on stricter options until strict is on and the escape hatches are rare.
{ "compilerOptions": { "allowJs": true, "checkJs": false, "noEmit": true, "strict": false }, "include": ["src"] }
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
A step-by-step order
- Add TypeScript and a
tsconfig.jsonwithallowJs,noEmitand your existing module settings. Runtscin CI as a check only; your current build keeps producing the output. - Install type packages for dependencies that do not ship their own types (
@types/nodeand the like). - Check JavaScript gradually.
checkJsfor the whole project is usually too noisy. Put// @ts-checkat the top of single files, or enablecheckJsand add// @ts-nocheckto files you are not ready for. Types can be written in JSDoc comments, so the files stay.js. - Rename files to
.ts, starting with modules that import nothing from your own code. Fix the errors in each file, then merge. - Model your data. Write interfaces for the domain objects first; most
anydisappears once those exist. - Tighten. Turn on
noImplicitAny, thenstrictNullChecks, then the rest, or switch onstrictand turn individual flags off. Fix one flag per pull request. - Add the extras.
noUncheckedIndexedAccess,exactOptionalPropertyTypesandverbatimModuleSyntaxare worth considering once the basics are green.
Handling the awkward parts
- Unknown shapes: use
unknownfor incoming data and validate it; see Runtime validation. - Dynamic objects:
Record<string, T>or an index signature, notany. - Old module formats: CommonJS
requirefiles may needesModuleInterop; see esModuleInterop. - Third-party code without types: write a small declaration file; see Declaration files.
- Tests: convert them last, or rename them early so mocks are typed; either order works.
Usage notes
- Keep behavior changes out of the migration. A type-only pull request is easy to review; one that also refactors is not.
- Prefer
@ts-expect-errorto@ts-ignore. The former reports an error when the suppression is no longer needed. - Count your escape hatches. Track the number of
any,asand@ts-comments over time; the number should fall. allowJsdoes not type-check by itself. It only lets.jsfiles take part in the program; addcheckJsor@ts-checkto get errors.- Do not chase 100% on day one. A project with
stricton and a few annotated suppressions beats one that stalls halfway. - Build tooling can change last. Many teams keep Babel or esbuild for output and use
tsc --noEmitonly for checking.