JavaScript to TypeScript Migration Best Practices

Guide for taking a JavaScript codebase to strict, modern TypeScript without a big-bang rewrite. Contains 42 rules across 7 categories, prioritized by impact to drive an incremental, file-by-file migration that keeps the build compiling at every step.

When to Apply

Reference these guidelines when:

• Converting a .js codebase to .ts (whole project or one module at a time)
• Adding types to existing JavaScript via JSDoc or annotations
• Choosing a tsconfig and allowJs strategy for a mixed JS/TS repo
• Turning on strict mode or individual strict flags on a large codebase
• Replacing any, as casts, and ! assertions left over from a quick conversion
• Validating external data (JSON, env, API responses) so the types you wrote are true at runtime
• Converting CommonJS to ESM, prototypes to classes, and other JS idioms to TS
• Updating the build, runner, and CI to type-check and publish TypeScript

How the Migration Flows