How to Migrate from JavaScript to TypeScript: A Step-by-Step Guide

TypeScript is a popular superset of JavaScript that adds static types and other features to the dynamic language. TypeScript can help you write more robust and maintainable code, catch errors at compile time, and leverage powerful tooling support. If you have an existing JavaScript project and want to take advantage of TypeScript, this guide will show you how to migrate your codebase gradually and smoothly.

Step 1: Create a tsconfig.json file

The first step is to create a tsconfig.json file in the root of your project. This file tells TypeScript how to compile your code, what files to include, and what options to use. You can start with a simple configuration like this:

{
  "compilerOptions": {
    "target": "es5", // Transpile to ES5
    "module": "commonjs", // Use CommonJS modules
    "outDir": "built", // Output directory for compiled files
    "strict": true // Enable strict mode for TypeScript
  },
  "include": ["src"] // Include source files in src directory
}

You can customize this file according to your project’s needs. For more details on the available options, see the TypeScript documentation.

Step 2: Rename your .js files to .ts

The next step is to rename your .js files to .ts. This will tell TypeScript to treat them as TypeScript files and check them for errors. If you use JSX in your files, you need to rename them to .tsx instead.

You can use a tool like rename-cli to rename multiple files at once. For example, to rename all .js files in the src directory to .ts, you can run:

npx rename-cli src/**/*.js --replace=.js --with=.ts

Step 3: Fix any errors reported by TypeScript

After renaming your files, you may see some red squiggles in your editor or some errors in the terminal when you run tsc. These are the places where TypeScript found some issues with your code and needs your help to fix them. Some of these errors may be legitimate bugs, while others may be due to TypeScript being too strict or not understanding your code.

You can go through these errors one by one and decide how to deal with them. Here are some common scenarios and solutions:

• Missing types: TypeScript may complain that it cannot find the type of a variable, parameter, or return value. This may happen because you are using a library that does not have type declarations, or because you are using a dynamic feature of JavaScript that TypeScript cannot infer. In these cases, you can either install type declarations for the library (if available), or use type annotations or type assertions to tell TypeScript what type you expect. For example:

// Install type declarations for lodash
npm install --save-dev @types/lodash

// Use type annotations for parameters and return values
function add(a: number, b: number): number {
  return a + b;
}

// Use type assertions to cast values to a specific type
let input = document.getElementById("input") as HTMLInputElement;

• Type mismatches: TypeScript may report that a value has a different type than expected. This may happen because you are passing an incorrect argument to a function, assigning an incompatible value to a variable, or returning a wrong value from a function. In these cases, you need to either fix the logic error, or use a union type or an overload to allow multiple types. For example:

// Fix the logic error by passing a string instead of a number
let message = "Hello";
console.log(message.toUpperCase());

// Use a union type to allow both string and number
let value: string | number = "42";
value = 42;

// Use an overload to define multiple signatures for a function
function format(value: string): string;
function format(value: number): string;
function format(value: any): string {
  return value.toString();
}

• Null and undefined values: TypeScript may warn you that a value may be null or undefined when you try to access its properties or methods. This may happen because you are using a value that is optional, uninitialized, or nullable. In these cases, you need to either check for null or undefined before using the value, or use the optional chaining or nullish coalescing operators to handle them gracefully. For example:

// Check for null or undefined before using the value
let name = person?.name; // name may be undefined

if (name) {
  console.log(name.toUpperCase());
}

// Use optional chaining to access properties or methods safely
let name = person?.name?.toUpperCase(); // name may be undefined

// Use nullish coalescing to provide a default value
let name = person?.name ?? "Unknown"; // name is never undefined

Step 4: Enable more strict options for TypeScript

Once you have fixed all the errors reported by TypeScript, you can enable more strict options to get even more safety and analysis from the compiler. These options can help you avoid common pitfalls, enforce best practices, and catch more bugs. Some of the recommended options are:

• noImplicitAny: This option prevents TypeScript from inferring the type any for a value that it cannot determine the type of. This can help you avoid using any unintentionally and losing type safety.
• noImplicitThis: This option prevents TypeScript from inferring the type any for the this keyword when it is used outside of classes or interfaces. This can help you avoid using this incorrectly and losing context.
• noUnusedParameters: This option reports an error when a function parameter is declared but never used. This can help you avoid unnecessary parameters and improve readability.
• noUnusedLocals: This option reports an error when a local variable is declared but never used. This can help you avoid unnecessary variables and improve performance.

You can enable these options by adding them to the compilerOptions section of your tsconfig.json file. For example:

{
  "compilerOptions": {
    // ...
    "noImplicitAny": true,
    "noImplicitThis": true,
    "noUnusedParameters": true,
    "noUnusedLocals": true
  },
  // ...
}

You can find more strict options and their descriptions in the TypeScript documentation.

Step 5: Enjoy the benefits of TypeScript

Congratulations! You have successfully migrated your JavaScript project to TypeScript. You can now enjoy the benefits of TypeScript, such as:

• Type checking: TypeScript can catch errors at compile time, such as type mismatches, null or undefined values, unused variables or parameters, and more. This can help you write more robust and maintainable code, and save you time and effort in debugging.
• Tooling support: TypeScript can provide you with powerful tooling support, such as code completion, refactoring, navigation, documentation, and more. This can help you write code faster, easier, and with less mistakes.
• Future features: TypeScript can transpile your code to a lower version of JavaScript that is compatible with older browsers or environments. This can help you use the latest features of JavaScript without worrying about compatibility issues.

I hope this guide was helpful for you to migrate from JavaScript to TypeScript.

If you have any questions or feedback, please let us know in the comments below.