Skip to content
Tutorials Center
My learning

Topics

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.

JSON
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "noEmit": true,
    "strict": false
  },
  "include": ["src"]
}

Try it

TypeScript Typing a plain JavaScript function in place

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.

TypeScript Escape hatches with an expiry date

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

  1. Add TypeScript and a tsconfig.json with allowJs, noEmit and your existing module settings. Run tsc in CI as a check only; your current build keeps producing the output.
  2. Install type packages for dependencies that do not ship their own types (@types/node and the like).
  3. Check JavaScript gradually. checkJs for the whole project is usually too noisy. Put // @ts-check at the top of single files, or enable checkJs and add // @ts-nocheck to files you are not ready for. Types can be written in JSDoc comments, so the files stay .js.
  4. Rename files to .ts, starting with modules that import nothing from your own code. Fix the errors in each file, then merge.
  5. Model your data. Write interfaces for the domain objects first; most any disappears once those exist.
  6. Tighten. Turn on noImplicitAny, then strictNullChecks, then the rest, or switch on strict and turn individual flags off. Fix one flag per pull request.
  7. Add the extras. noUncheckedIndexedAccess, exactOptionalPropertyTypes and verbatimModuleSyntax are worth considering once the basics are green.

Handling the awkward parts

  • Unknown shapes: use unknown for incoming data and validate it; see Runtime validation.
  • Dynamic objects: Record<string, T> or an index signature, not any.
  • Old module formats: CommonJS require files may need esModuleInterop; 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-error to @ts-ignore. The former reports an error when the suppression is no longer needed.
  • Count your escape hatches. Track the number of any, as and @ts- comments over time; the number should fall.
  • allowJs does not type-check by itself. It only lets .js files take part in the program; add checkJs or @ts-check to get errors.
  • Do not chase 100% on day one. A project with strict on 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 --noEmit only for checking.