Lumina

Manuals / TypeScript / Ch 9

D · IntegrationAdvanced45 min read

9. Migration strategy

TypeScript · 44 pages source format

Migrate incrementally — never big-bang rewrite. allowJs + checkJs → rename leaves → tighten strict → delete any. JavaScript consumes TypeScript; TypeScript compiles to JS. Keep shipping throughout.

What you'll learn

  • allowJs / checkJs
  • Rename order (leaves first)
  • JSDoc migration path
  • Incremental strict
  • Team rollout

Enable allowJs

tsconfig: allowJs: true, checkJs: true (optional). .ts and .js coexist. TypeScript checks JSDoc-annotated JS.

Do this now

Add allowJs to tsconfig. Run typecheck — note JS + TS errors together.

Clear?

Migration order

1) Utils (no dependencies). 2) Types/models. 3) API layer. 4) UI/DOM last. Each step: rename, fix errors, commit, ship.

  • Step 1 — utils + types (leaf nodes)
  • Step 2 — api module
  • Step 3 — render/DOM module
  • Step 4 — main entry + tests
  • Step 5 — remove allowJs, all .ts

Do this now

Write 5-step migration plan for your js-journey repo. Mark step 1 complete.

Clear?

JSDoc first path

For large legacy: add @ts-check + JSDoc types before rename. Lower risk, slower payoff.

Do this now

Pick one .js file not yet migrated. Add @ts-check and JSDoc. Fix errors without rename.

Clear?

Handling any debt

// @ts-expect-error with ticket link for known debt. Never silent @ts-ignore. Track any count — should decrease weekly.

Do this now

Grep for any in project. List each with plan to remove. Fix one today.

Clear?

CI typecheck gate

Add npm run typecheck to CI before tests. PRs cannot merge with type errors.

# .github/workflows/ci.yml snippet
- run: npm run typecheck
- run: npm run test:run

Do this now

Add typecheck step to GitHub Actions or document local pre-push ritual.

Clear?

Checklist