Course contentsShow
← JavaScript
Lesson 2645 of 2,72353. Type Safety Without TypeScriptFree lesson

Incremental Adoption in Legacy Codebases

Adding type safety gradually with JSDoc annotations before committing to a TypeScript migration.

Incremental Adoption in Legacy Codebases

You'll learn how to gradually introduce type safety to existing JavaScript projects using JSDoc annotations without committing to a full TypeScript rewrite.

The Challenge of Legacy Code

Large, established JavaScript codebases often can't afford a complete halt for migration. Converting thousands of files to TypeScript overnight is risky, expensive, and disruptive. JSDoc annotations offer a middle path: you add type safety incrementally, file by file, without changing your build process or tooling.

The Incremental Strategy

Think of it like renovating a house one room at a time while still living there. You don't need to move out (migrate everything) to start improving safety.

Start with high-risk areas: modules that cause frequent bugs, handle critical business logic, or serve as public APIs. Add @type, @param, and @returns annotations to document contracts. Enable @ts-check only in these files initially.

// Start here: critical utility functions
/**
 * @param {number} price
 * @param {number} taxRate
 * @returns {number}
 */
function calculateTotal(price, taxRate) {
  return price * (1 + taxRate);
}

As confidence grows, expand type coverage to adjacent modules. Use @typedef to define shared types in central files, then import them elsewhere. The beauty: zero runtime changes. Your code continues running identically while gaining compile-time safety.

Once you've annotated 30-50% of critical paths and proven the value, you can evaluate whether full TypeScript migration makes sense—or simply continue with JSDoc indefinitely.

Progressive Enhancement

Enable jsconfig.json with "checkJs": false initially, then opt individual files in with @ts-check. This prevents overwhelming teams with thousands of errors on day one.

Key Takeaway: JSDoc lets you add type safety gradually to legacy JavaScript projects, reducing risk by allowing incremental adoption without disrupting existing workflows or requiring immediate tooling changes.