typescript

TypeScript Best Practices (for JS/JSX Type-Checking)

This guide outlines essential TypeScript best practices for teams working with JavaScript or JSX files that are type-checked by TypeScript (e.g., via tsconfig.json with allowJs and/or JSDoc annotations). While many examples use native TypeScript syntax for clarity and conciseness, the underlying principles and type-safety benefits apply directly to your .js/.jsx codebase.

1. Enable Strict Mode in tsconfig.json

This is the single most impactful change you can make. strict: true enables a suite of crucial checks that catch the vast majority of common type-related bugs at compile time.

Action: Ensure your tsconfig.json includes:

// tsconfig.json
{
  "compilerOptions": {
    "strict": true, // Enables all strict type-checking options
    "noImplicitAny": true, // Catches untyped variables/parameters
    "strictNullChecks": true, // Prevents `null`/`undefined` access without checks
    "strictPropertyInitialization": true, // Ensures class properties are initialized
    "allowJs": true, // Crucial for type-checking .js/.jsx files
    "checkJs": true, // Enables type-checking in .js/.jsx files
    // ... other options
  },
  "include": ["**/*.js", "**/*.jsx"] // Ensure your JS/JSX files are included
}

2. Define Clear Type Contracts

Use interfaces and type aliases to describe the shape of your data, especially for API payloads, component props, and complex objects. For .js/.jsx files, leverage JSDoc to apply these types.

✅ GOOD: Interfaces for Object Shapes & Classes

Interfaces are ideal for defining the shape of objects and for implementing explicit contracts when working with classes. Define these in .d.ts or .ts files, then reference them in JSDoc.

// types.d.ts or types.ts
interface UserProfile {
  id: string;
  name: string;
  email: string;
  age?: number; // Optional property
}

interface Point {
  readonly x: number;
  readonly y: number;
}