TypeScript as documentation, not a safety net

Most teams introduce TypeScript and immediately start fighting it. They sprinkle any everywhere, disable strict mode, and wonder why they still have runtime errors. They've missed the point.

TypeScript is not a runtime safety net. The types disappear at runtime. JavaScript doesn't care what types you declared. TypeScript is a communication tool—it tells future you, and everyone else on the team, what a function expects and what it returns.

Types Communicate Intent

// This tells me nothing:
function processOrder(data: any): any {
    // ...
}

// This tells me everything before I read the body:
function processOrder(order: Order): ProcessedOrder {
    // ...
}

When you write any, you're opting out of that communication. It's not TypeScript being difficult—it's you choosing not to document.

Strict Mode Matters

Add this to your tsconfig.json and don't disable it:

{
  "compilerOptions": {
    "strict": true
  }
}

Strict mode catches null dereferences, unchecked optional chaining, and implicit any parameters. Most "TypeScript is annoying" complaints come from projects running without strict mode—getting 30% of the value.

Stop Fighting the Type System

When the compiler tells you something is wrong, it's almost always right. The instinct to cast your way out of an error with as SomeType usually means you haven't modeled your data correctly.

Fix the model, not the cast.

Where to Apply the Rigor

Types are great for function signatures, API response shapes, domain models, and component props. Apply the rigor at the boundaries—where data enters and leaves your modules.

TypeScript won't prevent all bugs. But it makes your codebase self-documenting and your refactors far safer. That's enough reason to do it right.