Learning Guides
Menu

Migrating to TypeScript

2 min read•Effective TypeScript

Migrating to TypeScript

Big-bang migrations are risky. The best strategy is incremental, which lets you ship continuously while improving type safety.

Item 63: Start With allowJs and checkJs

JSON
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true
  }
}

This enables TypeScript to check JavaScript files and surface problems without converting anything yet.

Item 64: Use JSDoc for Quick Wins

JSDoc gives immediate type checking in .js files:

JAVASCRIPT
/** @param {string} name */
function greet(name) {
  return `Hello, ${name}`;
}

This can uncover issues before you rename files.

Item 65: Convert One Boundary at a Time

Prioritize modules with clear inputs/outputs:

  • API client
  • Database layer
  • Utility libraries

Define types at boundaries and let core logic follow naturally.

Item 66: Add Types for Domain Models First

Types for your core data (User, Order, Invoice) unlock benefits everywhere.

TYPESCRIPT
interface User {
  id: string;
  email: string;
  role: "admin" | "user";
}

Item 67: Convert Files Opportunistically

When you touch a file, convert it. This keeps migration aligned with real work and avoids a massive refactor sprint.

Item 68: Use unknown at the Edges

During migration, it’s tempting to use any. Prefer unknown instead, and add guards in small steps.

TYPESCRIPT
function parseLegacy(input: unknown): NewType {
  if (!isNewType(input)) throw new Error("Invalid");
  return input;
}

Item 69: Isolate @ts-nocheck

If you must, use it in a single file to keep the build green. Add a TODO so it doesn’t linger.

TYPESCRIPT
// @ts-nocheck TODO: remove after migration

Item 70: Enable Strictness Gradually

If strict mode is too much at first, enable flags in order:

  1. noImplicitAny
  2. strictNullChecks
  3. noImplicitThis
  4. strictFunctionTypes
  5. strictPropertyInitialization

Item 71: Track Progress in CI

Run tsc --noEmit in CI and track error counts over time. This turns migration into a measurable goal.

Migration Checklist

Note

✅ Enable allowJs + checkJs ✅ Add JSDoc to critical files ✅ Define domain models ✅ Convert boundary modules ✅ Convert files as you touch them ✅ Turn on strict flags gradually

Key Takeaways

  1. Incremental migration is safest.
  2. Use JSDoc and checkJs for early value.
  3. Start with domain types and boundaries.
  4. Prefer unknown over any.
  5. Enable strictness step by step.

Next: generics and type parameters.