On this page

JavaScript to TypeScript Migration Guide

Updated on June 24, 2026

Enrico Hochkoeppler Profile

By Enrico Hochkoeppler

Web Developer & TutoriaLibre Founder

Migrating a JavaScript project to TypeScript does not require a complete rewrite. TypeScript is designed to integrate seamlessly with existing JavaScript codebases, allowing for a gradual, file-by-file migration. The TypeScript compiler accepts JavaScript files as input when allowJs is enabled, and type checking can be incrementally introduced using checkJs and JSDoc annotations. This approach enables teams to adopt TypeScript at their own pace, converting files as needed while maintaining a fully functional codebase throughout the process.


Incremental Migration Strategy​

A successful migration from JavaScript to TypeScript follows a predictable, low-risk sequence. The key principle is that every existing JavaScript file is already valid TypeScript. This means you can rename files from .js to .ts one at a time and address type errors incrementally.

The recommended migration flow:

  1. Set up TypeScript — Install TypeScript and create a tsconfig.json file
  2. Enable JavaScript support — Configure allowJs: true to accept .js files as input
  3. Add JSDoc annotations — Add type hints to critical JavaScript files without converting them
  4. Enable type checking — Use // @ts-check or checkJs: true to catch errors
  5. Rename files incrementally — Convert .js files to .ts one at a time
  6. Increase strictness — Enable strict: true and other compiler options gradually
  7. Remove JavaScript support — Disable allowJs once all files are converted

Step 1 — Setting Up TypeScript​

Installing TypeScript​

Install TypeScript as a development dependency:


npm install --save-dev typescript @types/node

Code explanation: The --save-dev flag adds TypeScript to the devDependencies section of package.json. @types/node provides type definitions for Node.js core modules, which is essential for server-side projects.

Creating the Configuration File​

Initialize a tsconfig.json file:


npx tsc --init

Code explanation: The tsc --init command generates a default tsconfig.json file with commonly used compiler options commented out. This file controls how TypeScript compiles your code.

Basic tsconfig.json for Migration​

For a migration project, start with a configuration that accepts JavaScript files:


{

  "compilerOptions": {

    "outDir": "./built",

    "allowJs": true,

    "target": "ES2020",

    "module": "commonjs"

  },

  "include": ["./src/**/*"]

}

Code explanation: outDir specifies where compiled output files should be placed. allowJs: true tells TypeScript to accept .js files as input. target sets the JavaScript version for the output. include tells TypeScript which files to process.

Separating Input and Output Directories​

During migration, it is important to keep source files separate from compiled output to prevent TypeScript from overwriting original files. A typical structure looks like:


projectRoot/

├── src/

│   ├── file1.js

│   └── file2.js

├── built/

└── tsconfig.json

Code explanation: Source files reside in src/, while compiled output goes to built/. This separation ensures that original JavaScript files remain intact during the migration process.


Step 2 — Using allowJs and checkJs​

allowJs: Compiling JavaScript Files​

The allowJs compiler option enables TypeScript to process .js files alongside .ts files. This is the foundation of incremental migration, as it allows JavaScript and TypeScript files to coexist and import from each other.

Key benefits of allowJs:

checkJs: Type-Checking JavaScript Files​

The checkJs option enables type checking for .js files:


{

  "compilerOptions": {

    "allowJs": true,

    "checkJs": true

  }

}

Code explanation: When checkJs is enabled, TypeScript reports type errors in JavaScript files just as it would in TypeScript files. This provides immediate feedback without requiring file renaming.

Per-File Type Checking with @ts-check​

For projects that are not ready to enable checkJs globally, type checking can be enabled on a per-file basis:


// @ts-check



/** @type {number} */

var x;

x = 0; // OK

x = false; // Error: Type 'boolean' is not assignable to type 'number'

Code explanation: The // @ts-check comment at the top of a JavaScript file enables TypeScript type checking for that file only. This is useful for testing type checking on critical files before enabling it project-wide.

Skipping Type Checking​

To disable type checking for specific files, add // @ts-nocheck to the top of the file. To ignore errors on specific lines, use // @ts-ignore or // @ts-expect-error on the preceding line.


Step 3 — JSDoc-Based Typing​

JSDoc annotations provide a way to add type information to JavaScript files without converting them to TypeScript. This is particularly useful for large legacy codebases where converting all files at once is impractical.

Annotating Parameters and Return Types​


/**

 * Adds two numbers together.

 * @param {number} a - The first number

 * @param {number} b - The second number

 * @returns {number} The sum of a and b

 */

function add(a, b) {

  return a + b;

}

Code explanation: The @param tags specify the types of the function parameters. The @returns tag specifies the return type. TypeScript uses these annotations for type checking when checkJs or // @ts-check is enabled.

Defining Custom Types​


/**

 * @typedef {Object} User

 * @property {number} id

 * @property {string} name

 * @property {string} email

 */



/**

 * @param {User} user

 * @returns {string}

 */

function getUserDisplayName(user) {

  return `${user.name} (${user.email})`;

}

Code explanation: The @typedef tag defines a custom type named User. This type can then be used in @param and @returns tags throughout the file.

Importing Types from TypeScript Files​

When working with mixed JavaScript and TypeScript codebases, JSDoc can import types from .ts files:


/**

 * @typedef {import("./types").User} User

 */



/**

 * @param {User} user

 */

function printUser(user) {

  console.log(user.name);

}

Code explanation: The import("./types").User syntax imports the User type from a TypeScript file. This enables type sharing between JavaScript and TypeScript files without converting the JavaScript file.


Step 4 — Renaming Files to TypeScript​

Once the project is set up with allowJs and basic type checking, individual files can be renamed from .js to .ts.

File Renaming Strategy​

Start with files that have the fewest dependencies and the clearest types. Utility functions, helper modules, and configuration files are good candidates to convert first.


utils.js → utils.ts

Code explanation: Simply renaming the file extension triggers TypeScript compilation. TypeScript will report any type errors that need to be addressed.

Addressing Type Errors​

When a file is renamed to .ts, TypeScript will report type errors. Common issues include:

Type Inference​

TypeScript can often infer types without explicit annotations. For example:


let name = "John"; // TypeScript infers string

let count = 10; // TypeScript infers number

let items = [1, 2, 3]; // TypeScript infers number[]

Code explanation: TypeScript infers types from variable initialization. This reduces the amount of explicit type annotations needed during migration.


Step 5 — Gradually Increasing Strictness​

TypeScript offers multiple levels of strictness. Starting with a permissive configuration and gradually enabling stricter options reduces migration friction.

Enabling Strict Mode​

Once the project compiles without errors, enable strict: true in tsconfig.json:


{

  "compilerOptions": {

    "strict": true

  }

}

Code explanation: strict: true enables a suite of strict type-checking options, including noImplicitAny, strictNullChecks, strictFunctionTypes, and others.

Individual Strict Options​

If enabling all strict options at once is too burdensome, enable them one by one:


{

  "compilerOptions": {

    "noImplicitAny": true,

    "strictNullChecks": true,

    "strictFunctionTypes": true,

    "noUncheckedIndexedAccess": true

  }

}

Code explanation: noImplicitAny catches variables and parameters with implicit any types. strictNullChecks prevents null and undefined from being assigned to non-nullable types. strictFunctionTypes enforces stricter checking on function types. Each option improves type safety incrementally.

Early Benefits​

Even before full migration, TypeScript provides benefits:


Putting It All Together: A Complete Migration Workflow​

1. Start with JavaScript Only​


src/

  index.js

  utils.js

2. Add TypeScript with allowJs​


{

  "compilerOptions": {

    "outDir": "./built",

    "allowJs": true,

    "target": "ES2020"

  },

  "include": ["./src/**/*"]

}

Run npx tsc to verify that compilation works.

3. Add JSDoc Types to Critical Files​


/**

 * @param {string} name

 * @returns {string}

 */

function greet(name) {

  return `Hello, ${name}!`;

}

4. Enable Type Checking​

Add // @ts-check to the top of important files or enable checkJs: true in tsconfig.json.

5. Convert One File to TypeScript​


utils.js → utils.ts

Fix any type errors that appear.

6. Convert More Files Over Time​

Continue renaming files one by one. Use @ts-ignore for temporary workarounds if needed.

7. Disable JavaScript Support​

Once all files are converted, disable allowJs and checkJs:


{

  "compilerOptions": {

    "allowJs": false,

    "checkJs": false

  }

}

Migration complete.


Summary​

Migrating a JavaScript project to TypeScript is a gradual, low-risk process that allows teams to adopt type safety at their own pace. The key strategies are:

Incremental migration — Convert files one by one rather than all at once. Every JavaScript file is already valid TypeScript, so renaming files is the primary action.

allowJs and checkJs — Enable JavaScript file compilation and type checking. This allows JavaScript and TypeScript to coexist during migration.

JSDoc annotations — Add type information to JavaScript files without converting them. This is ideal for large legacy codebases.

Gradual strictness — Start with permissive settings and enable stricter options over time.

This is exactly how real companies migrate to TypeScript—slowly, safely, and with minimal disruption.

Found this helpful? Share the knowledge...

... or support this project to keep it alive!

Buy Me a Coffee

Previous

Working with Existing JavaScript Codebases

Next

Interoperability