Guide
Add a tsconfig, measure your type errors, convert files from the bottom of your import graph upward, and type-check after every batch. Below are the real steps with code, and an honest look at the tools that can do parts of the work for you: ts-migrate, AI coding agents and CodeMorph.
Windows 10/11 · Free during beta · Bring your own Claude key or use Ollama
Windows may show 'unknown publisher'. Click More info, then Run anyway.
The steps
These steps work with any tool, or with none. They are the same ones the tools below automate in different ways.
Commit everything, and make sure your tests pass before you touch a file. If a test fails later, you want to know the migration caused it. Create a branch for the work so every step can be reviewed and undone.
Install TypeScript as a dev dependency, along with the type definitions for the Node version you target.
npm install --save-dev typescript @types/nodeStart loose. The goal of this step is to let JavaScript and TypeScript files live side by side, so you can convert one file at a time and always have a working project. The allowJs option is what makes that possible.
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "Bundler",
"allowJs": true,
"checkJs": false,
"noEmit": true,
"strict": false,
"esModuleInterop": true,
"resolveJsonModule": true,
"skipLibCheck": true
},
"include": ["src"]
}Adjust module and moduleResolution to match how your project runs. For a bundler or Next.js project the values above work as written. For a plain Node project, use the Node settings from the TypeScript docs.
Turn on checkJs once, run the compiler, and count the errors. Your JavaScript already has type errors, mostly places where the compiler can see a value is used inconsistently. That number is your baseline, and progress is measured against it, not against zero.
npx tsc --noEmit --checkJs --maxNodeModuleJsDepth 0 | grep -c "error TS"On an untyped codebase this is often in the hundreds or thousands. That is normal. Do not try to fix it all at once.
Before you convert a file, make sure the packages it imports have types. Many popular packages ship their own. For the rest, install the matching @types package. For a package with no types at all, declare it once so imports stop failing.
npm install --save-dev @types/express @types/lodashdeclare module "some-untyped-package";Types flow upward through imports. If you convert a file before the files it imports, you have to guess what those imports return. If you convert the imports first, the answer is already in a typed file. So start with the files that import nothing local, such as utilities and helpers, and work toward your entry point. Files that import each other in a cycle have to move together.
Here is a typical leaf file. Rename it from .js to .ts, switch to ES module syntax and add the types the code already implies.
function formatMoney(cents, currency = "USD") {
return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(cents / 100);
}
module.exports = { formatMoney };export function formatMoney(cents: number, currency: string = "USD"): string {
return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(cents / 100);
}src/orders.js:14:21 - error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.Now every file that imports formatMoney is checked against the real signature. If a caller passes a string where it should pass a number, the compiler tells you, and that is the kind of bug migrations exist to find.
After each batch of files, run tsc across the whole project, not just the files you changed. A change to a typed module can break the files that import it. When an error appears, resist the quick escape of any. Use unknown for values you cannot trust yet, and narrow them.
// Avoid: the compiler stops checking everything downstream
function getId(input: any) {
return input.id;
}
// Prefer: say what you know, and check the rest
function getId(input: unknown): string {
if (typeof input === "object" && input !== null && "id" in input && typeof input.id === "string") {
return input.id;
}
throw new Error("Expected an object with a string id");
}Once every file is TypeScript, tighten the configuration one flag at a time instead of turning on strict all at once. Fix the errors each flag reveals, commit, then move on.
{
"compilerOptions": {
"noImplicitAny": true,
"strictNullChecks": true,
"strictFunctionTypes": true
// when all of these are clean, replace them with:
// "strict": true
}
}Add the type-check to CI so a pull request with type errors cannot merge. This is the step that makes the migration permanent.
name: typecheck
on: [pull_request]
jobs:
tsc:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
- run: npm ci
- run: npx tsc --noEmitThe tools
You can run all of the steps above by hand. These are the ways people automate the conversion, with what each one does well and where it stops.
npm install --save-dev ts-migrate
npx -p ts-migrate -c "ts-migrate-full src"CodeMorph vs ts-migrateBest tools to migrate JavaScript to TypeScript
Choosing
| Your situation | What fits |
|---|---|
| A handful of files, or a project you know well | Do it by hand with the compiler, and use an AI assistant for tricky files. |
| Hundreds or thousands of files, and you mainly need it to compile soon | ts-migrate, then pay down the any and @ts-expect-error comments over time. |
| A mid-size or large codebase, and you want real types with every step checked | CodeMorph, or an AI agent you drive carefully with tsc after each batch. |
| You cannot send code to any AI provider | By hand or ts-migrate, or CodeMorph with a local model through Ollama. |
Download the beta, open a project and see your migration plan in under a minute.
Windows 10/11 · Free during beta · Bring your own Claude key or use Ollama
Windows may show 'unknown publisher'. Click More info, then Run anyway.