typescript

TypeScript Best Practices

Quick Start

Apply these rules by default when touching TypeScript/JavaScript:

1. Enable strict: true in tsconfig.json (most impactful change)
2. Define clear type contracts with interfaces/type aliases
3. Use unknown instead of any; narrow with type guards
4. Implement runtime validation for external data (APIs, user input)
5. Prefer string literal unions over numeric enums
6. Use named exports, avoid default exports

Workflow (use this order)

1. Clarify scope: new code, refactor, or review.
2. Enforce strictness in tsconfig.json (or confirm it is already strict).
3. Define explicit type contracts for inputs/outputs (interfaces/type aliases).
4. Replace any with unknown + narrowing/guards.
5. Add runtime validation for external data boundaries.
6. Normalize exports/imports and tighten API surfaces.
7. Add or update tests for changed behavior.

Review Checklist

• Strict mode enabled and no any leaks.
• Public types are explicit and documented.
• Runtime validation exists for untrusted inputs.
• Literal unions used instead of numeric enums.
• Named exports only; imports are organized.
• Tests cover edge cases and error paths.

Local Resources

Use the always-applied rule file in this folder:

• typescript.mdc (authoritative TypeScript/JSX guidance; read when you need the full rule text)

Configuration

Essential tsconfig.json settings:

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictPropertyInitialization": true,
    "allowJs": true,
    "checkJs": true
  }
}

Type Definitions

Interfaces for Object Shapes

Use interfaces for object shapes and class contracts. Define in .d.ts or .ts files, reference via JSDoc in .js files.

interface UserProfile {
  id: string;
  name: string;
  email: string;
  age?: number;
}

Type Aliases for Unions & Complex Types

Use type aliases for unions, intersections, and tuples.