Typescript Migration: The Migration Guide That Actually Works

// tsconfig.json — start permissive, tighten gradually
{
 "compilerOptions": {
 "target": "ES2020",
 "module": "ESNext",
 "moduleResolution": "bundler",
 "allowJs": true, // Let TypeScript coexist with JavaScript
 "checkJs": false, // Don't error on .js files yet
 "strict": false, // Start permissive
 "noImplicitAny": false, // Allow implicit any for now
 "outDir": "./dist",
 "rootDir": "./src",
 "sourceMap": true,
 "declaration": true
 },
 "include": ["src/**/*"]
}
// At this stage: TypeScript compiles but doesn't complain
// Rename files from .js to .ts one at a time as you add types

// Enable in this order (each catches a different bug class):

// Week 1: noImplicitAny — catch untyped parameters
// "noImplicitAny": true
// Error: function add(a, b) { return a + b; } — a and b need types

// Week 2: strictNullChecks — catch null/undefined bugs
// "strictNullChecks": true
// Error: const name = user.getName(); name.toUpperCase();
// user.getName() might return null!

// Week 3: strictFunctionTypes — catch callback type mismatches
// "strictFunctionTypes": true

// Week 4: strict: true — enables all remaining strict checks
// "strict": true
// Includes: strictBindCallApply, strictPropertyInitialization, noImplicitThis

// Final: tighten further
// "noUncheckedIndexedAccess": true -- arr[i] returns T | undefined
// "exactOptionalPropertyTypes": true -- explicit vs missing properties

interface User { id: number; name: string; email: string; createdAt: Date; }

// Partial — all properties optional (update payloads)
type UpdateUser = Partial; // { id?: number; name?: string; ... }

// Required — all properties required (reverse Partial)
type RequiredUser = Required>;

// Pick — select specific properties
type UserPreview = Pick; // { id: number; name: string }

// Omit — exclude specific properties
type UserWithoutDates = Omit;

// Record — typed object/map
type RolePermissions = Record<'admin' | 'user' | 'guest', string[]>;

// ReturnType — extract function return type
type ApiResponse = ReturnType; // Inferred from function

// Parameters — extract function parameter types
type FetchParams = Parameters; // [id: string, options?: Options]

// Awaited — unwrap Promise type
type ResolvedUser = Awaited>; // User, not Promise

// any: opt out of type checking — dangerous
function bad(value: any) {
 value.toUpperCase(); // No error! Crashes at runtime if value is number
}

// unknown: must narrow before use — safe
function good(value: unknown) {
 // value.toUpperCase(); // Error: unknown has no methods
 if (typeof value === 'string') {
 value.toUpperCase(); // Now TypeScript knows it's a string
 }
}

// Use unknown for:
// - Function parameters you don't control (API responses, event handlers)
// - JSON.parse() return value (always returns any — cast to unknown first)
const raw: unknown = JSON.parse(apiResponse);
// Now narrow with type guard before using