~ Contribute

Suggest a correction or improvement. The author reviews it before it goes live.

Comment0 / 300

en/tutorials/ts/14ts-best-practices

# TypeScript Best Practices

Guidelines for writing effective, maintainable, and type-safe TypeScript code.

## Enable Strict Mode

Always enable strict mode in `tsconfig.json`:

```json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}
```

**Remember:** Strict mode catches the most common bugs and ensures all types are explicit.

## Avoid `any`

Use specific types, `unknown`, or generics instead:

```typescript
// Bad
function process(data: any): any { return data; }

// Good
function process(data: { name: string; age: number }): string {
  return `${data.name} is ${data.age}`;
}

// Better — unknown + type guard
function process(data: unknown): string {
  if (typeof data === "string") return data;
  return "Unknown";
}
```

## Use Interfaces for Object Shapes

Interfaces support declaration merging, extending, and class implementation:

```typescript
interface User {
  name: string;
  age: number;
}

interface Admin extends User {
  role: string;
}
```

**Tip:** Prefer interfaces over type aliases for object shapes that might be extended.

## Annotate Function Signatures

Always annotate parameters and return types to document your API:

```typescript
function calculateTotal(items: { price: number }[], taxRate: number): number {
  return items.reduce((sum, item) => sum + item.price, 0) * (1 + taxRate);
}
```

## Use Discriminated Unions

Cleaner than complex if/else chains:

```typescript
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rectangle"; width: number; height: number };

function getArea(shape: Shape): number {
  switch (shape.kind) {
    case "circle": return Math.PI * shape.radius ** 2;
    case "rectangle": return shape.width * shape.height;
  }
}
```

## Use Partial for Optional Parameters

`Partial` makes all properties optional while keeping types safe:

```typescript
interface Options {
  timeout: number;
  retries: number;
  debug: boolean;
}

function configure(options: Partial<Options>): void {
  const defaults: Options = { timeout: 5000, retries: 3, debug: false };
  const settings = { ...defaults, ...options };
}
```

## Best Practices

- Enable strict mode always
- Avoid `any` — use specific types, `unknown`, or generics
- Use interfaces for object shapes
- Annotate function signatures
- Use `as const` for literal types
- Prefer discriminated unions over complex conditionals
- Use `Partial` for optional parameter objects
- Generate declaration files for libraries
- Run the linter to enforce consistent style

## Common Mistakes

- Using `any` excessively defeats TypeScript's purpose
- Not enabling strict mode misses many type errors
- Overusing type assertions bypasses type safety
- Ignoring compiler warnings leads to hidden bugs
- Not using return type annotations misses type mismatches

No changes yet

cancel