TypeScript Migration: Add Types to a Large JavaScript Codebase (2026)

Adding types to a large JavaScript codebase is less about transforming code and more about building a safety net that catches bugs before they ever reach production.

Let’s see this in action with a hypothetical, yet common, scenario. Imagine you have a JavaScript function that processes user data:

// users.js
function processUser(user) {
  if (user.isActive) {
    console.log(`Welcome back, ${user.name}!`);
  } else {
    console.log(`Hello, ${user.name}. Your account is inactive.`);
  }
}

const user1 = { name: "Alice", isActive: true };
const user2 = { name: "Bob", isActive: false };

processUser(user1);
processUser(user2);

Now, let’s introduce TypeScript. First, we need to set up tsconfig.json. A minimal configuration to get started might look like this:

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2016",
    "module": "CommonJS",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*.ts", "src/**/*.js"],
  "exclude": ["node_modules"]
}

The key here is strict: true. This enables a suite of strict type-checking options, including noImplicitAny, strictNullChecks, and strictFunctionTypes, which are crucial for catching the most common JavaScript pitfalls.

Now, we rename users.js to users.ts and define the expected shape of the user object:

// src/users.ts
interface User {
  name: string;
  isActive: boolean;
}

function processUser(user: User) {
  if (user.isActive) {
    console.log(`Welcome back, ${user.name}!`);
  } else {
    console.log(`Hello, ${user.name}. Your account is inactive.`);
  }
}

const user1: User = { name: "Alice", isActive: true };
const user2: User = { name: "Bob", isActive: false };

processUser(user1);
processUser(user2);

If you try to call processUser with an object that doesn’t match the User interface, TypeScript will flag it during compilation:

const invalidUser = { username: "Charlie", active: true };
// Error: Argument of type '{ username: string; active: boolean; }' is not assignable to parameter of type 'User'.
// Object literal may only specify known properties, and 'username' does not exist in type 'User'. Did you mean to use 'name'?
// Property 'active' does not exist in type 'User'. Did you mean to use 'isActive'?
processUser(invalidUser);

This is the core benefit: explicit contracts prevent unexpected data shapes from causing runtime errors.

The mental model for migrating a large codebase involves several stages. First, you’ll set up your tsconfig.json with strictness enabled. Then, you’ll incrementally convert .js files to .ts. For each file, you define interfaces or types that describe the data structures being passed around. This often involves looking at how data is actually used, not just how it’s intended to be used.

For existing JavaScript libraries, you’ll rely on DefinitelyTyped (@types/library-name) to provide type definitions. If a library is missing types, you might need to create your own ambient declaration files (.d.ts) to describe its API.

The "least surprising" approach is to start with the most critical or most frequently modified parts of your codebase. This allows you to build confidence and establish patterns before tackling the more complex or legacy sections. Gradual adoption is key; you don’t need to convert everything overnight.

One of the most powerful, yet often overlooked, aspects of TypeScript is its ability to infer types. You don’t always have to explicitly write user: User. If you declare a variable and assign it a value that conforms to an interface, TypeScript can infer the type:

const newUser = { name: "David", isActive: true }; // TypeScript infers newUser is of type User
processUser(newUser); // This works because newUser is correctly typed by inference.

This inference capability significantly reduces the amount of boilerplate you need to write, making the code cleaner while still providing type safety. It’s not just about adding annotations; it’s about leveraging the compiler’s intelligence.

The next step after getting your core application typed is often exploring advanced type manipulation and dealing with third-party libraries that have complex or missing type definitions.