Migrating JavaScript Projects to TypeScript

Migrate a JavaScript project gradually: add TypeScript tooling, enable allowJs/checkJs as appropriate, annotate selected modules, and turn on stricter checks incrementally. Runtime tests remain important because changing file extensions does not validate external data or change business logic.

The TypeScript version of a small JavaScript function makes both numeric parameters explicit. A real staged migration might first add JSDoc to existing .js files and move a subset to .ts.

Renaming foo.js to foo.ts is not enough if modules, untyped dependencies, or runtime assumptions remain incompatible.

Save as migrating-javascript-projects.ts. The following program passed strict TypeScript compilation, and the displayed output was captured by executing its emitted JavaScript with Node.js 22.16.0.

TypeScript source

/** @param {number} price @param {number} quantity */
function bill(price: number, quantity: number): number { return price * quantity; }
console.log(bill(12, 3));

Verified output

36

Compile: npx tsc --strict --target es2022 --module commonjs migrating-javascript-projects.ts; run: node migrating-javascript-projects.js. For Node.js API examples, install @types/node first. For browser projects, use the browser-specific instructions below.

The example demonstrates the code-level behavior; the related configuration or test commands are shown separately when needed.

The TypeScript version of a small JavaScript function makes both numeric parameters explicit. A real staged migration might first add JSDoc to existing .js files and move a subset to .ts.

Predict what changes if you alter one input. Then run the code to compare your reasoning with the real output.

Practical project lab: These are real configuration and source-file examples, not a TypeScript object that merely describes settings. Place the files at the named paths relative to one project directory.

tsconfig.json

{"compilerOptions":{"allowJs":true,"checkJs":true,"noEmit":true,"strict":true},"include":["src/**/*.js"]}

src/bill.js

/** @param {number} price @param {number} quantity */
function bill(price, quantity) { return price * quantity; }
console.log(bill(12, 3));

Commands

npx tsc -p .

JSDoc and checkJs make a first migration step without renaming every file.

This local compiler or test-runner mini-project was validated in addition to the primary program.

Renaming foo.js to foo.ts is not enough if modules, untyped dependencies, or runtime assumptions remain incompatible.

Identify whether the failure is a type-checking issue, a configuration issue, or a runtime behavior issue before choosing a fix.

Create a JS file with JSDoc annotations, enable checkJs, then convert it to .ts and compare diagnostics.

Write down your expected result first. For configuration examples, compare compiler output and diagnostics; for test examples, make the assertion fail deliberately to verify that the tool reports it.

For the exact current options and platform behavior, consult the official documentation. These examples were verified using the tool versions described above.

Migrate a JavaScript project gradually: add TypeScript tooling, enable allowJs/checkJs as appropriate, annotate selected modules, and turn on stricter checks incrementally.

Run the primary example, then complete the practice task or environment-specific lab.