Chapter 15: Project 3: Migrating a JavaScript Project to TypeScript

Introduction

Welcome back, intrepid coder! In our journey so far, we’ve explored the incredible power and flexibility of TypeScript, building new projects from the ground up with type safety as our guiding star. But what about all those existing JavaScript projects out there? The ones that are already running, perhaps in production, and doing just fine… for now?

In this chapter, we’re going to tackle a super practical and incredibly common scenario: migrating an existing JavaScript project to TypeScript. This isn’t just about learning new syntax; it’s about strategizing, incrementally adding types, and transforming a dynamic codebase into a robust, type-safe one without breaking everything along the way. You’ll learn how to introduce TypeScript gradually, making your code more maintainable, easier to refactor, and less prone to runtime errors.

Before we dive in, make sure you’re comfortable with the core TypeScript concepts we’ve covered in previous chapters, including basic types, interfaces, functions, classes, and modules. We’ll be applying all that knowledge to an existing JavaScript codebase, so a solid foundation will make this migration smooth sailing!

Core Concepts: The Art of Gradual Migration

Migrating a large JavaScript project to TypeScript can feel like trying to change a tire on a moving car – daunting, right? But it doesn’t have to be! The beauty of TypeScript is its ability to coexist with JavaScript. This means we can adopt it incrementally, file by file, or even function by function.

Why Migrate? Reaping the Rewards

You’ve heard it before, but it’s worth reiterating why this effort pays off:

Catch Errors Early: TypeScript catches a huge class of errors (like typos in variable names, incorrect function arguments) before your code even runs. This saves debugging time and prevents production bugs.
Improved Code Quality & Maintainability: Explicit types act as living documentation, making your code easier to understand for you and your teammates. Refactoring becomes safer and more reliable.
Better Developer Experience: Modern IDEs (like VS Code) leverage TypeScript’s type information to provide amazing autocomplete, intelligent suggestions, and instant feedback, boosting your productivity.
Scalability: As projects grow, managing complexity in plain JavaScript becomes harder. TypeScript provides the structure needed for large, collaborative applications.

Migration Strategy: A Gentle Approach

We’ll primarily focus on a “strangler fig” pattern for migration. Think of a strangler fig tree that grows around an existing tree, eventually becoming the dominant structure. In software, this means:

Preparation: Set up TypeScript in your existing JavaScript project without changing any .js files yet.
Configuration: Tweak tsconfig.json to allow JavaScript files and gradually enable stricter checks.
Incremental Conversion: Pick a small, isolated part of your codebase (a utility file, a single module) and convert it from .js to .ts.
Type as You Go: Introduce types, interfaces, and possibly any temporarily for parts that are too complex to type immediately (but aim to eliminate any later!).
Test & Iterate: After each conversion step, run your tests to ensure nothing broke.

This approach minimizes risk and allows you to experience the benefits of TypeScript without a massive, all-at-once refactor.

The `tsconfig.json` for Migration

The tsconfig.json file is your TypeScript compiler’s instruction manual. When migrating, a few key options become super important:

"allowJs": true: This tells the TypeScript compiler to also process .js files. Essential for gradual migration!
"checkJs": true: When allowJs is true, checkJs enables type checking for .js files. This is a fantastic intermediate step, as TypeScript will infer types and warn you about potential issues in your JavaScript code before you even convert it to .ts.
"outDir": Where your compiled JavaScript files will go.
"rootDir": The root of your source files.
"strict": true: We always aim for strict mode, but you might disable it initially and enable specific strict flags later if the migration is too overwhelming.

These settings allow TypeScript to “watch” over your JavaScript files, gently guiding you towards type safety.

Step-by-Step Implementation: Migrating a Simple Utility Module

Let’s get our hands dirty! We’ll start with a small, fictional JavaScript project containing a few utility functions and a simple class.

1. Setting Up Our JavaScript Project

First, let’s create a new directory for our project and initialize it with npm.

Open your terminal and run:

mkdir js-to-ts-migration
cd js-to-ts-migration
npm init -y

This creates a package.json file for us.

Now, let’s create a simple JavaScript file named src/utils.js. Create a src directory first:

mkdir src

Then, open src/utils.js and add the following content:

// src/utils.js

/**
 * Greets a user by name.
 * @param {string} name - The name of the user.
 * @returns {string} The greeting message.
 */
function greet(name) {
  return `Hello, ${name}!`;
}

/**
 * Calculates the area of a rectangle.
 * @param {number} width - The width of the rectangle.
 * @param {number} height - The height of the rectangle.
 * @returns {number} The area of the rectangle.
 */
function calculateRectangleArea(width, height) {
  return width * height;
}

/**
 * Represents a simple user.
 */
class User {
  constructor(id, name, email) {
    this.id = id;
    this.name = name;
    this.email = email;
  }

  getDetails() {
    return `User ID: ${this.id}, Name: ${this.name}, Email: ${this.email}`;
  }
}

module.exports = {
  greet,
  calculateRectangleArea,
  User
};

Notice the JSDoc comments (/** ... */)! These are super helpful because TypeScript can read them and infer types. This is a common best practice in JavaScript projects that makes migration much easier.

Let’s also create an index.js file to use our utilities:

// index.js

const { greet, calculateRectangleArea, User } = require('./src/utils');

console.log(greet("Alice"));
console.log(calculateRectangleArea(10, 5));

const user1 = new User(1, "Bob", "[email protected]");
console.log(user1.getDetails());

// An intentional error for later!
// console.log(greet(123)); // This would be a runtime error in JS

You can run this project with node index.js to see it in action.

2. Installing TypeScript

Now, let’s bring TypeScript into the mix! We’ll install the latest stable version of TypeScript as a development dependency. As of 2025-12-05, the latest stable release is TypeScript 5.9.3.

npm install --save-dev [email protected]

You should see typescript added to your devDependencies in package.json.

3. Initializing `tsconfig.json`

Next, we need to create a tsconfig.json file, which configures the TypeScript compiler. We can generate a basic one using npx tsc --init.

npx tsc --init

This command creates a tsconfig.json file in your project root. It will be quite verbose with many commented-out options. Let’s simplify it for our current needs and add the crucial migration flags.

Open tsconfig.json and replace its content with this simplified version:

// tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",                       /* Specify ECMAScript target version for compiled JavaScript. */
    "module": "CommonJS",                     /* Specify module code generation: 'CommonJS', 'ESNext', etc. */
    "outDir": "./dist",                       /* Redirect output structure to the directory. */
    "rootDir": "./",                          /* Specify the root directory of source files. */
    "strict": true,                           /* Enable all strict type-checking options. */
    "esModuleInterop": true,                  /* Emit additional JavaScript to ease support for importing CommonJS modules. */
    "skipLibCheck": true,                     /* Skip type checking all .d.ts files. */
    "forceConsistentCasingInFileNames": true, /* Ensure that casing is consistent throughout a file. */
    "allowJs": true,                          /* Allow JavaScript files to be compiled. */
    "checkJs": true,                          /* Enable error reporting in .js files. */
    "resolveJsonModule": true,                /* Allow importing .json files. */
    "sourceMap": true                         /* Generate .map files for debugging. */
  },
  "include": [
    "src/**/*.js",
    "src/**/*.ts",
    "index.js",
    "index.ts"
  ],
  "exclude": [
    "node_modules",
    "dist"
  ]
}

Let’s break down the important additions and changes for migration:

"target": "ES2022": We’re targeting a modern JavaScript version. Feel free to adjust based on your environment.
"module": "CommonJS": Since our original JavaScript uses module.exports and require, we’ll stick with CommonJS for now. If your project uses ESM (import/export), you’d set this to ESNext or NodeNext.
"outDir": "./dist": All compiled .js files will go into a dist folder.
"rootDir": "./": Our source files can be anywhere within the project root.
"strict": true: This is our ultimate goal! Starting with true often reveals many errors. For a very large project, you might start with false and enable individual strict flags (like noImplicitAny, noUnusedLocals) gradually. But for our small project, true is good!
"allowJs": true: Crucial for migration! This tells TypeScript to not just compile .ts files, but also to parse and potentially emit .js files.
"checkJs": true: Equally crucial! With allowJs enabled, checkJs makes TypeScript type-check your .js files. It will use JSDoc comments (like the ones we added to utils.js) and type inference to find potential issues.
"include": Specifies which files TypeScript should consider part of the project. We include both .js and .ts files in src and our root index file.

4. Running TypeScript with `checkJs`

Before we even convert a single file, let’s see what TypeScript thinks of our existing JavaScript code with checkJs enabled.

Add a build script to your package.json:

// package.json (add this line to "scripts" object)
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  },

Now, run the build command:

npm run build

What do you see? If you’ve followed along, you might not see any errors initially, which is great! This means our JSDoc comments were sufficient for TypeScript to understand our utils.js file.

Now, let’s introduce that intentional error in index.js we commented out earlier. Modify index.js to uncomment the problematic line:

// index.js

const { greet, calculateRectangleArea, User } = require('./src/utils');

console.log(greet("Alice"));
console.log(calculateRectangleArea(10, 5));

const user1 = new User(1, "Bob", "[email protected]");
console.log(user1.getDetails());

console.log(greet(123)); // This is now active!

Save index.js and run npm run build again.

Boom! You should now see an error message from TypeScript, something like:

src/index.js:9:17 - error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

9 console.log(greet(123));
                  ~~~~

Isn’t that amazing? TypeScript just caught a potential runtime error in our plain JavaScript file before we even ran it! This is the power of checkJs. It uses type inference and JSDoc to provide feedback.

Go ahead and comment out console.log(greet(123)); again in index.js to resolve the error for now.

5. Converting `src/utils.js` to `src/utils.ts`

Now for the real conversion! We’ll start with src/utils.js.

First, rename the file:

mv src/utils.js src/utils.ts

Next, open src/utils.ts. Because we had good JSDoc, TypeScript already understands a lot. We can now replace the JSDoc with native TypeScript syntax for clarity and stronger type guarantees.

Here’s the original src/utils.js content:

// src/utils.js (original content for reference)

/**
 * Greets a user by name.
 * @param {string} name - The name of the user.
 * @returns {string} The greeting message.
 */
function greet(name) {
  return `Hello, ${name}!`;
}

/**
 * Calculates the area of a rectangle.
 * @param {number} width - The width of the rectangle.
 * @param {number} height - The height of the rectangle.
 * @returns {number} The area of the rectangle.
 */
function calculateRectangleArea(width, height) {
  return width * height;
}

/**
 * Represents a simple user.
 */
class User {
  constructor(id, name, email) {
    this.id = id;
    this.name = name;
    this.email = email;
  }

  getDetails() {
    return `User ID: ${this.id}, Name: ${this.name}, Email: ${this.email}`;
  }
}

module.exports = {
  greet,
  calculateRectangleArea,
  User
};

Now, let’s transform src/utils.ts step-by-step:

Step 5.1: Convert greet function

Original JS:

/**
 * Greets a user by name.
 * @param {string} name - The name of the user.
 * @returns {string} The greeting message.
 */
function greet(name) {
  return `Hello, ${name}!`;
}

To TS: We add type annotations directly to the parameter and return type.
```
function greet(name: string): string {
  return `Hello, ${name}!`;
}
```
Explanation: We explicitly tell TypeScript that name must be a string and that the greet function will always return a string. This is much clearer and more robust than relying on JSDoc.

Step 5.2: Convert calculateRectangleArea function

Original JS:

/**
 * Calculates the area of a rectangle.
 * @param {number} width - The width of the rectangle.
 * @param {number} height - The height of the rectangle.
 * @returns {number} The area of the rectangle.
 */
function calculateRectangleArea(width, height) {
  return width * height;
}

To TS: Similar to greet, we add number types.
```
function calculateRectangleArea(width: number, height: number): number {
  return width * height;
}
```
Explanation: Both width and height are numbers, and their product (the area) is also a number.

Step 5.3: Convert User class

This is where TypeScript really shines for classes!

Original JS:

/**
 * Represents a simple user.
 */
class User {
  constructor(id, name, email) {
    this.id = id;
    this.name = name;
    this.email = email;
  }

  getDetails() {
    return `User ID: ${this.id}, Name: ${this.name}, Email: ${this.email}`;
  }
}

To TS: We add property declarations with types, and parameter types to the constructor.
```
class User {
  id: number;
  name: string;
  email: string;

  constructor(id: number, name: string, email: string) {
    this.id = id;
    this.name = name;
    this.email = email;
  }

  getDetails(): string {
    return `User ID: ${this.id}, Name: ${this.name}, Email: ${this.email}`;
  }
}
```
Explanation:
- id: number;, name: string;, email: string;: We declare the types of the instance properties before the constructor. This is a key difference from JavaScript.
- constructor(id: number, name: string, email: string): The constructor parameters are also typed.
- getDetails(): string: The method’s return type is specified.
Shorthand for Class Properties: TypeScript offers a convenient shorthand for declaring and initializing class properties directly in the constructor:
```
class User {
  constructor(public id: number, public name: string, public email: string) {}

  getDetails(): string {
    return `User ID: ${this.id}, Name: ${this.name}, Email: ${this.email}`;
  }
}
```
Explanation: By adding public (or private, protected, readonly) before a constructor parameter, TypeScript automatically creates a property of that name and type on the class instance and assigns the constructor argument to it. Much cleaner! We’ll use this modern shorthand.

Step 5.4: Convert module.exports to export

Original JS:

module.exports = {
  greet,
  calculateRectangleArea,
  User
};

To TS: TypeScript prefers ES Modules syntax (export).

export {
  greet,
  calculateRectangleArea,
  User
};

Or even better, export directly:

export function greet(name: string): string { /* ... */ }
// ...
export class User { /* ... */ }

We’ll use direct exports.

Putting it all together in src/utils.ts:

After all these steps, your src/utils.ts file should look like this:

// src/utils.ts

export function greet(name: string): string {
  return `Hello, ${name}!`;
}

export function calculateRectangleArea(width: number, height: number): number {
  return width * height;
}

export class User {
  constructor(public id: number, public name: string, public email: string) {}

  getDetails(): string {
    return `User ID: ${this.id}, Name: ${this.name}, Email: ${this.email}`;
  }
}

Now, run npm run build again. If everything is correct, you should see no errors! TypeScript successfully compiled src/utils.ts into dist/src/utils.js (and dist/src/utils.js.map).

6. Updating `index.js` to `index.ts`

Our index.js file is still JavaScript. It’s importing from utils.js. Since utils.ts is now compiled to dist/src/utils.js, our index.js could still work if it imports from dist/src/utils.js. However, the goal is to make index.ts use the types from utils.ts.

First, rename index.js to index.ts:

mv index.js index.ts

Now, open index.ts.

Original JS:

// index.js

const { greet, calculateRectangleArea, User } = require('./src/utils');

console.log(greet("Alice"));
console.log(calculateRectangleArea(10, 5));

const user1 = new User(1, "Bob", "[email protected]");
console.log(user1.getDetails());

To TS: We need to change require to import statements, as utils.ts now uses export.

// index.ts

import { greet, calculateRectangleArea, User } from './src/utils';

console.log(greet("Alice"));
console.log(calculateRectangleArea(10, 5));

const user1 = new User(1, "Bob", "[email protected]");
console.log(user1.getDetails());

// Let's try the error again, but now in TypeScript!
// console.log(greet(123));

Notice that we changed require('./src/utils') to import ... from './src/utils'. TypeScript automatically resolves this to src/utils.ts.

Now, run npm run build. Again, no errors! TypeScript has compiled index.ts to dist/index.js.

Finally, let’s test our migrated project. Remember the start script we added to package.json?

npm run start

You should see the output:

Hello, Alice!
50
User ID: 1, Name: Bob, Email: [email protected]

Success! You’ve just migrated your first JavaScript files to TypeScript.

7. Re-introducing the Error (and fixing it with types!)

Let’s uncomment that problematic line in index.ts again:

// index.ts

import { greet, calculateRectangleArea, User } from './src/utils';

console.log(greet("Alice"));
console.log(calculateRectangleArea(10, 5));

const user1 = new User(1, "Bob", "[email protected]");
console.log(user1.getDetails());

console.log(greet(123)); // Re-enabled!

Run npm run build. You’ll get the same error as before, but now directly from our TypeScript file:

index.ts:9:17 - error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.

9 console.log(greet(123));
                  ~~~~

This clearly shows TypeScript doing its job. To fix it, simply change 123 back to a string:

console.log(greet("Charlie")); // Fixed!

Run npm run build again. No errors! This demonstrates how TypeScript guides you to write correct code.

Mini-Challenge: Migrate a Configuration Loader

You’re doing great! Now it’s your turn to apply what you’ve learned.

Challenge: Imagine you have a simple JavaScript module that loads configuration from a file and provides a function to get a specific setting. Your task is to migrate this module to TypeScript.

Create a new JavaScript file: src/config.js with the following content:

// src/config.js

const defaultConfig = {
  apiUrl: "https://api.example.com/v1",
  timeout: 5000,
  debugMode: false
};

/**
 * Retrieves a configuration setting.
 * @param {string} key - The key of the setting to retrieve.
 * @returns {any} The value of the setting.
 */
function getSetting(key) {
  if (key in defaultConfig) {
    return defaultConfig[key];
  }
  console.warn(`Warning: Configuration key '${key}' not found.`);
  return undefined;
}

module.exports = {
  getSetting
};

Without changing src/config.js yet, run npm run build. Observe if TypeScript (with checkJs) finds any issues. Hint: Pay attention to the return type of getSetting.
Rename src/config.js to src/config.ts.
Add appropriate TypeScript types to src/config.ts. Think about:
- The type of defaultConfig. Can you use a type alias or interface for it?
- The parameter key for getSetting.
- The return type of getSetting. Can you make it more specific than any? (This is a trickier one, consider a type union or generics if you’re feeling advanced, but any might be a temporary step. The goal is to move away from any.)
Update index.ts to import getSetting from src/config using ES Module syntax, and then use it to log a setting (e.g., apiUrl).
Run npm run build again and verify there are no errors.

Hint: For the defaultConfig object, an interface or type alias would be perfect! For getSetting, consider the type of key and what the possible return types could be. If you’re stuck on the return type, unknown is often a better starting point than any if you want to be type-safe.

What to observe/learn: This challenge highlights how TypeScript can infer types from object literals and how to explicitly define types for configuration objects. It also pushes you to think about the return types of functions that access dynamic properties.

Click for Solution Hint!

For the `defaultConfig` object, you can define an interface like this:


  interface AppConfig {
    apiUrl: string;
    timeout: number;
    debugMode: boolean;
  }

Then, you can declare `defaultConfig` as: `const defaultConfig: AppConfig = { ... };`. For `getSetting`, the `key` parameter should be a `keyof AppConfig`. The return type could be `AppConfig[keyof AppConfig]`, which would be a union of all possible value types (`string | number | boolean | undefined`).

Common Pitfalls & Troubleshooting

Migrating a project can bring up unique challenges. Here are a few common pitfalls and how to navigate them:

Over-reliance on any:
- Pitfall: When faced with complex types or external JavaScript, it’s tempting to sprinkle any everywhere to make the errors go away. This defeats the purpose of TypeScript!
- Solution: Use any as a temporary bandage, not a long-term solution. When you use any, make a mental note (or a TODO comment) to come back and type it properly. Often, unknown is a safer alternative if you truly don’t know the type, as it forces you to perform type checks before using the value.
- Best Practice: Aim for noImplicitAny (which is part of strict: true).
Missing Type Declarations for Third-Party Libraries:
- Pitfall: You migrate your code, but now TypeScript complains about require('lodash') or import React from 'react' because it doesn’t know the types for these libraries.
- Solution: Most popular JavaScript libraries have community-maintained type definitions available on npm, usually in the @types/ scope. For example, for lodash, you’d install npm install --save-dev @types/lodash. For Node.js built-in modules, you’d install npm install --save-dev @types/node.
- Official Docs: Search the DefinitelyTyped repository for types.
tsconfig.json Configuration Issues:
- Pitfall: Incorrect module, target, outDir, rootDir settings can lead to compilation errors, files not being found, or incorrect output.
- Solution: Double-check your tsconfig.json.
  - module: Should match your project’s module system (CommonJS for require/module.exports, ESNext or NodeNext for import/export).
  - target: Should be compatible with your runtime environment (e.g., ES2022 for modern Node.js, older ES5 if targeting older browsers).
  - outDir and rootDir: Ensure they correctly point to your output and source directories, respectively.
  - include / exclude: Make sure all files you want TypeScript to process are included, and node_modules and your outDir are excluded.
Initial Overwhelm from Strict Mode Errors:
- Pitfall: Enabling "strict": true (or individual strict flags like noImplicitAny, strictNullChecks) on a large JavaScript codebase can result in hundreds or thousands of errors, which can be discouraging.
- Solution: Don’t feel pressured to fix everything at once. You can start with "strict": false and gradually enable individual strict flags one by one (e.g., noImplicitAny: true, then strictNullChecks: true, etc.) as you tackle the errors they reveal. Prioritize fixing errors in the files you are actively migrating. The goal is to reach full strictness eventually, but a phased approach is often necessary.

Summary

Phew! You’ve just completed a crucial step in becoming a TypeScript master: migrating an existing JavaScript project. Let’s recap what you’ve learned:

Why Migrate: The compelling reasons for adopting TypeScript, including early error detection, improved maintainability, and enhanced developer experience.
Gradual Strategy: The power of incremental migration using allowJs and checkJs to slowly introduce type safety without a “big bang” rewrite.
tsconfig.json for Migration: How to configure your TypeScript compiler with options like allowJs, checkJs, outDir, and rootDir to support mixed JS/TS codebases.
Step-by-Step Conversion: The practical process of renaming .js files to .ts, adding explicit type annotations to functions, classes, and variables, and updating module syntax.
Catching Errors Early: How TypeScript provides immediate feedback on type mismatches, even in JavaScript files (with checkJs), preventing runtime bugs.
Common Pitfalls: Strategies for avoiding and resolving issues like any abuse, missing type declarations for libraries, and configuration headaches.

You’ve now got a powerful new tool in your arsenal for bringing the benefits of TypeScript to any project, regardless of its starting point. This skill is highly valued in the industry, as many companies have legacy JavaScript codebases that could benefit from TypeScript’s safety and tooling.

In the next chapter, we’ll continue to explore advanced TypeScript features and patterns, building on the strong foundation you’ve established. Keep up the fantastic work!

Chapter 15: Project 3: Migrating a JavaScript Project to TypeScript

Table of Contents

Introduction

Core Concepts: The Art of Gradual Migration

Why Migrate? Reaping the Rewards

Migration Strategy: A Gentle Approach

The tsconfig.json for Migration

Step-by-Step Implementation: Migrating a Simple Utility Module

1. Setting Up Our JavaScript Project

2. Installing TypeScript

3. Initializing tsconfig.json

4. Running TypeScript with checkJs

5. Converting src/utils.js to src/utils.ts

6. Updating index.js to index.ts

7. Re-introducing the Error (and fixing it with types!)

Mini-Challenge: Migrate a Configuration Loader

Common Pitfalls & Troubleshooting

Summary

The `tsconfig.json` for Migration

3. Initializing `tsconfig.json`

4. Running TypeScript with `checkJs`

5. Converting `src/utils.js` to `src/utils.ts`

6. Updating `index.js` to `index.ts`