---

name: typescript description: Enforces modern TypeScript best practices for type-safe code, strict configuration, runtime validation, and clear type contracts. Use when writing or reviewing TypeScript/JavaScript code, configuring tsconfig.json, or when the user asks for TypeScript style guidance.

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

Configuration

Essential tsconfig.json settings:

Copy{
  "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.

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

Type Aliases for Unions & Complex Types

Use type aliases for unions, intersections, and tuples.

Copytype ID = string | number;
type UserRole = "admin" | "user" | "guest";
type Coords = [number, number];

Type Safety

Avoid any, Use unknown

any bypasses all type checks. unknown forces narrowing before use.

❌ Bad:

Copyfunction processData(data: any) {
  console.log(data.foo.bar); // No type safety
}

✅ Good:

Copyfunction processData(data: unknown) {
  if (typeof data === 'object' && data !== null && 'foo' in data) {
    const typed = data as { foo: { bar: string } };
    console.log(typed.foo.bar);
  }
}

Runtime Validation

TypeScript's checks are compile-time only. For external data (APIs, user input), implement runtime validation with type guards.

Type Guards for Primitives

Copyfunction isString(value: unknown): value is string {
  return typeof value === 'string';
}

function isNumber(value: unknown): value is number {
  return typeof value === 'number' && !isNaN(value);
}

Type Guards for Complex Objects

Copyinterface Product {
  id: string;
  name: string;
  price: number;
}

function isProduct(obj: unknown): obj is Product {
  return (
    typeof obj === 'object' && obj !== null &&
    'id' in obj && typeof obj.id === 'string' &&
    'name' in obj && typeof obj.name === 'string' &&
    'price' in obj && typeof obj.price === 'number'
  );
}

Enums and Unions

Prefer string literal unions over numeric enums for better type safety and simpler runtime representation.

❌ Bad:

Copyenum UserStatus {
  Active,    // 0
  Inactive,  // 1
  Pending    // 2
}

✅ Good:

Copytype UserStatus = 'active' | 'inactive' | 'pending';

// If enum is necessary, use const string enum:
const enum UserRole {
  Admin = "admin",
  User = "user",
  Guest = "guest"
}

Generics

Use generics for reusable, type-safe functions and components.

Copyfunction identity<T>(arg: T): T {
  return arg;
}

const num = identity(123);  // number
const str = identity("hello"); // string

Code Organization

Named Exports (No Default Exports)

Named exports promote explicit imports and easier refactoring.

❌ Bad:

Copyexport default class UserService { }

✅ Good:

Copyexport class UserService { }
export const DEFAULT_USER = { };

Organized Imports

Group imports: libraries → absolute paths → relative paths. Sort alphabetically.

Copyimport React from 'react';
import { useSelector } from 'react-redux';

import { API_URL } from 'config/constants';
import { selectUser } from 'store/selectors';

import { Button } from './components/Button';
import { formatCurrency } from '../utils/formatters';

Examples

Example 1: Type guard for API response

Input: "Validate and process API response" Output:

Copyinterface ApiUser {
  id: string;
  name: string;
  email: string;
}

function isApiUser(obj: unknown): obj is ApiUser {
  return (
    typeof obj === 'object' && obj !== null &&
    'id' in obj && typeof obj.id === 'string' &&
    'name' in obj && typeof obj.name === 'string' &&
    'email' in obj && typeof obj.email === 'string'
  );
}

async function fetchUser(id: string): Promise<ApiUser | null> {
  const response = await fetch(`/api/users/${id}`);
  const data: unknown = await response.json();
  
  if (isApiUser(data)) {
    return data;
  }
  return null;
}

Example 2: String literal union type

Input: "Status type with specific values" Output:

Copytype OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered';

function updateOrderStatus(orderId: string, status: OrderStatus) {
  // TypeScript ensures only valid status values
  console.log(`Order ${orderId} -> ${status}`);
}

updateOrderStatus('123', 'shipped'); // ✅ OK
// updateOrderStatus('123', 'invalid'); // ❌ Type error

Example 3: Generic utility function

Input: "Reusable function that works with any array type" Output:

Copyfunction getFirst<T>(items: T[]): T | undefined {
  return items[0];
}

const firstNum = getFirst([1, 2, 3]); // number | undefined
const firstStr = getFirst(['a', 'b']); // string | undefined

Example 4: JSDoc types for JavaScript files

Input: "Type-check JavaScript file with JSDoc" Output:

Copy// types.d.ts
export interface UserProfile {
  id: string;
  name: string;
  email: string;
}

// user-service.js
/**
 * @typedef {import('./types').UserProfile} UserProfile
 */

/**
 * @param {UserProfile} user
 * @returns {string}
 */
export function greetUser(user) {
  return `Hello, ${user.name}!`;
}