Migrating JavaScript to TypeScript

// tsconfig.json — lenient starting point
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,
    "strict": false,
    "noImplicitAny": false
  }
}

Common follow-ups: Why is a gradual, file-by-file migration generally safer than converting an entire codebase at once?

// tsconfig.json
{
  "compilerOptions": { "allowJs": true }
}
// Both utils.js and newFeature.ts can coexist and be imported from each other

Common follow-ups: What's the difference between 'allowJs' and 'checkJs'?

// @ts-check
/**
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function add(a, b) {
  return a + b;
}
add('1', 2); // Error caught even in a plain .js file

Common follow-ups: Which JSDoc tags does TypeScript understand for describing more complex types, like unions or generics?

// Migration path over several stages:
// Stage 1: { "strict": false, "noImplicitAny": true }
// Stage 2: add { "strictNullChecks": true }
// Stage 3: eventually { "strict": true }

Common follow-ups: Which individual strict-mode sub-flags tend to surface the most errors first in a typical migration?

// untyped-lib.d.ts
declare module 'untyped-lib';

// usage.ts
import untypedLib from 'untyped-lib'; // typed as 'any', but no longer a compile error

Common follow-ups: What's the risk of leaving a dependency typed as 'any' indefinitely, rather than eventually writing real types for it?

// tsconfig.json
{
  "compilerOptions": { "noImplicitAny": true },
  "exclude": ["src/legacy/**"] // temporarily exempted, shrinks over time
}

Common follow-ups: How could you track migration progress numerically, like percentage of files fully typed?

function getDiscount(user) { // plain JS, silently 'worked'
  if (user.isPremium) return 0.2;
  // no else branch -- implicitly returns undefined, used as a number elsewhere!
}
// TypeScript: function getDiscount(user): number is flagged, since not all paths return a number

Common follow-ups: Is it common for a TypeScript migration to actually catch real production bugs like this, beyond just adding type annotations?

// Before (PropTypes)
UserCard.propTypes = {
  name: PropTypes.string.isRequired,
  onClick: PropTypes.func
};

// After (TypeScript)
interface UserCardProps {
  name: string;
  onClick?: () => void;
}
function UserCard({ name, onClick }: UserCardProps) { /* ... */ }

Common follow-ups: What capability does PropTypes retain that pure compile-time TypeScript types lose, given TypeScript types don't exist at runtime?

function parseConfig(json: string): unknown {
  return JSON.parse(json);
}
const config = parseConfig(rawInput);
// config.someProperty; // Error: 'config' is of type 'unknown' -- must narrow first
if (typeof config === 'object' && config !== null && 'theme' in config) {
  console.log((config as { theme: string }).theme); // now safe
}

Common follow-ups: Why is defaulting to 'any' during migration considered a common anti-pattern that undermines the whole point of migrating?

// packages/core/tsconfig.json
{
  "compilerOptions": { "composite": true, "strict": true },
  "references": []
}

// packages/app/tsconfig.json
{
  "compilerOptions": { "strict": false },
  "references": [{ "path": "../core" }]
}

Common follow-ups: What build performance benefit do project references provide beyond just organizing migration strictness levels?