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

tsconfig & strategy → strictness ratchet → type the surfaces → kill any/casts
   → validate runtime boundaries → convert JS idioms → tooling/build/CI

Decisions at the front cascade: a wrong tsconfig or a top-down conversion order forces you to re-type modules twice, and an early any flood poisons everything downstream. Work from the front of this pipeline and from the leaves of the dependency graph inward.

Rule Categories by Priority

Quick Reference

1. Migration Setup & tsconfig (CRITICAL)

• setup-allowjs-checkjs-bridge — Enable allowJs and checkJs for incremental migration
• setup-migrate-leaves-first — Convert dependency leaves before their dependents
• setup-jsdoc-before-rename — Type JS with JSDoc and @ts-check before renaming
• setup-prefer-ts-expect-error — Prefer @ts-expect-error over @ts-ignore for suppressions
• setup-skiplibcheck-during-migration — Set skipLibCheck to silence third-party type noise
• setup-modern-module-resolution — Set module and moduleResolution to a modern pair
• setup-noemitonerror-isolatedmodules — Enable isolatedModules and noEmitOnError for safe output

2. Strictness Ratcheting (CRITICAL)

• strict-enable-flags-incrementally — Enable strict flags one at a time, not all at once
• strict-prioritize-null-checks — Prioritize strictNullChecks for the highest bug yield
• strict-no-implicit-any — Enable noImplicitAny to surface every untyped value
• strict-no-unchecked-indexed-access — Enable noUncheckedIndexedAccess for index safety
• strict-use-unknown-in-catch — Type caught errors as unknown, not any
• strict-exact-optional-property-types — Separate missing from undefined with exactOptionalPropertyTypes

3. Typing Public Surfaces (HIGH)

• surface-annotate-exported-signatures — Annotate exported function signatures explicitly
• surface-replace-jsdoc-with-types — Replace JSDoc type tags with real annotations
• surface-type-default-params — Type default and optional parameters precisely
• surface-interface-for-object-args — Convert loose object arguments to named interfaces
• surface-type-callbacks — Type callback and higher-order parameters
• surface-type-class-fields — Declare class field types instead of relying on assignment

4. Replacing any & Unsafe Casts (HIGH)

• unsafe-prefer-unknown-over-any — Replace any with unknown at untrusted boundaries
• unsafe-eliminate-as-casts — Replace as casts with narrowing or validation
• unsafe-avoid-double-assertion — Avoid double assertions that force unrelated types
• unsafe-type-dynamic-property-access — Type dynamic property access with Records or index signatures
• unsafe-replace-function-type — Replace the Function type with specific call signatures
• unsafe-narrow-instead-of-nonnull — Narrow values instead of using the non-null assertion

5. Runtime Data Validation (MEDIUM-HIGH)

• runtime-validate-external-data — Validate external data at the boundary
• runtime-type-environment-variables — Parse and type environment variables once
• runtime-derive-types-from-schemas — Derive static types from runtime schemas
• runtime-type-guards-at-boundaries — Write type guards for untyped library returns
• runtime-type-json-parse — Type JSON.parse results through validation

6. JS-to-TS Idiom Conversion (MEDIUM)

• idiom-require-to-import — Convert require and module.exports to ESM syntax
• idiom-prototype-to-class — Convert prototype constructors to class syntax
• idiom-type-only-imports — Use import type for type-only imports
• idiom-replace-arguments-object — Replace the arguments object with rest parameters
• idiom-enum-to-union-or-const — Convert frozen-object enums to const objects or unions
• idiom-default-export-to-named — Prefer named exports over default exports
• idiom-optional-chaining-over-guards — Replace manual existence guards with optional chaining

7. Tooling & Build Migration (LOW-MEDIUM)

• tooling-declare-untyped-modules — Provide ambient declarations for untyped dependencies
• tooling-install-types-packages — Install @types packages before casting library returns
• tooling-use-tsx-over-ts-node — Run TypeScript directly with tsx instead of ts-node flags
• tooling-emit-declaration-files — Emit declaration files for migrated libraries
• tooling-typecheck-in-ci — Add a type-check step to CI separate from the build

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions — Category structure and impact levels
• Rule template — Template for adding new rules

Related Skills

• typescript-refactor — Refactoring and modernizing code that is already TypeScript
• typescript-advanced-patterns — Advanced type-level patterns once the migration is done

Reference Files