Migrating JavaScript Projects Gradually

When you want to introduce TypeScript into an existing JavaScript project, a gradual approach is usually the most effective. This allows you to keep delivering features and bug fixes while incrementally improving type safety. There are several strategies you can use to migrate a codebase without disrupting your workflow. The most common methods include renaming JavaScript files to TypeScript files, enabling the allowJs compiler option to support both .js and .ts files, and using JSDoc comments to add type annotations directly in JavaScript files.

Renaming files is a straightforward way to start: you can change a file's extension from .js to .ts or .tsx (for React components), then begin adding explicit TypeScript types. However, this works best when you are ready to address any type errors that may arise.

Another popular method is to enable the allowJs option in your tsconfig.json file. This tells the TypeScript compiler to include .js files in the compilation process, allowing you to convert files incrementally. Additionally, you can use JSDoc comments to add type hints to your JavaScript code, which TypeScript understands and uses for type checking. This is especially useful when you want to get the benefits of type checking without immediately converting files to TypeScript.

// user.js with JSDoc annotations
/**
 * @param {string} name
 * @param {number} age
 * @returns {{name: string, age: number}}
 */
function createUser(name, age) {
  return { name, age };
}

// Before: users.js in a Node.js backend project
/**
 * @typedef {Object} User
 * @property {string} id
 * @property {string} email
 */

/**
 * @type {User[]}
 */
const users = [];

/**
 * @param {string} email
 * @returns {User}
 */
function addUser(email) {
  const user = { id: Date.now().toString(), email };
  users.push(user);
  return user;
}

module.exports = { addUser, users };