typescript-best-practices

When to use

Use this skill when working with TypeScript code. AI agents frequently generate outdated patterns - using any instead of unknown, type assertions instead of satisfies, optional fields instead of discriminated unions, and missing strict mode options. This skill enforces modern TypeScript 5.x patterns.

Critical Rules

1. Enable Strict Mode with All Checks

Wrong (agents do this):

{
  "compilerOptions": {
    "strict": false,
    "target": "ES2020"
  }
}

Correct:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "target": "ES2022"
  }
}

Why: Strict mode catches entire categories of bugs. noUncheckedIndexedAccess prevents unsafe array/object access. Agents often skip these for "convenience."

2. Use satisfies Instead of Type Assertions

Wrong (agents do this):

const config = {
  port: 3000,
  host: "localhost",
} as Config;

config.port.toFixed(); // No error even if port could be string

Correct:

const config = {
  port: 3000,
  host: "localhost",
} satisfies Config;

config.port.toFixed(); // TypeScript knows port is number

Why: satisfies validates the type without widening it. as silences the compiler and can hide bugs. Use satisfies for validation, as only when you genuinely know more than the compiler.

3. Use Discriminated Unions Over Optional Fields

Wrong (agents do this):

interface ApiResponse {
  data?: User;
  error?: string;
  loading?: boolean;
}

Correct:

type ApiResponse =
  | { status: "loading" }
  | { status: "success"; data: User }
  | { status: "error"; error: string };

Why: Optional fields allow impossible states (data AND error both present). Discriminated unions make each state explicit and exhaustively checkable.

4. Use const Assertions for Literal Types