Migrating and Living With TypeScript

// 1. Add TypeScript with the loosest possible config
{ "compilerOptions": { "allowJs": true, "strict": false, "noEmit": true } }

// 2. Convert leaf-first: utilities and types before components.
//    A typed module makes everything importing it better; a typed
//    component with untyped dependencies fights inference.

// 3. Turn on strict flags one at a time, fixing as you go
"noImplicitAny": true        // usually the largest single batch
"strictNullChecks": true     // usually the most valuable

// 4. Check JS files without renaming them
// @ts-check at the top of a .js file, with JSDoc types:
/** @param {string} slug @returns {Promise<Problem>} */
async function getProblem(slug) { ... }

// 5. Ratchet: never let the error count go up.
//    tsc --noEmit in CI, and each PR must not add errors.

// any infects everything downstream
const data: any = await res.json()
const name = data.user.name        // any
const upper = name.toUpperCase()   // any — no checking anywhere below

// unknown stops the spread at the source
const data: unknown = await res.json()
// forced to narrow before any use

// Suppressions, in order of preference
// @ts-expect-error — errors if the line STOPS failing, so it self-cleans
// @ts-ignore       — silent forever, including after the bug is fixed

// Find where any lives
npx type-coverage --detail        // percentage of typed expressions
// and forbid new ones:
// eslint: @typescript-eslint/no-explicit-any, no-unsafe-assignment

// Third-party modules with no types
declare module 'untyped-lib' {
  export function doThing(input: string): Promise<void>
}
// Better than 'any' — one small honest declaration instead of a hole.

// esbuild, swc, Vite, Next: transpile TypeScript by DELETING types.
// They are fast because they never type-check. Which means:
//   a broken type does not fail your dev server or your build.

// So run the checker separately, and in CI
"scripts": {
  "typecheck": "tsc --noEmit",
  "build": "next build",
  "ci": "npm run typecheck && npm run lint && npm test"
}

// Because types are stripped per-file, these need explicit syntax:
import type { User } from './types'        // erased for certain
export type { User }
"isolatedModules": true                    // enforces it

// Speed, for large repos
"incremental": true                        // caches in .tsbuildinfo
// project references to split the graph into checked units