TypeScript Best Practices for Large-Scale Applications

TypeScript has become the go-to language for building large-scale JavaScript applications. This guide covers essential best practices and patterns that will help you write more maintainable, scalable, and type-safe code.

Project Structure and Organization

1. Organize by Feature, Not by File Type

src/
├── components/
│   ├── Header/
│   │   ├── Header.tsx
│   │   ├── Header.types.ts
│   │   └── Header.test.tsx
│   └── Footer/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── types/
│   └── dashboard/
└── shared/
    ├── types/
    ├── utils/
    └── constants/

2. Use Barrel Exports

Create index.ts files to simplify imports:

// Usage
import { Button, Footer, Header } from '@/components'

export { Button } from './Button/Button'
export { Footer } from './Footer/Footer'
// components/index.ts
export { Header } from './Header/Header'

Type System Best Practices

1. Prefer Interfaces Over Types for Object Definitions

// Good: Interface for object shapes
interface User {
  id: string
  name: string
  email: string
}

// Good: Type for unions and computed types
type Status = 'loading' | 'success' | 'error'
type UserKeys = keyof User

2. Use Strict TypeScript Configuration

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noImplicitReturns": true,
    "noImplicitThis": true
  }
}

3. Leverage Utility Types

// Partial for optional properties
function updateUser(id: string, updates: Partial<User>) {
  // Implementation
}

// Pick for selecting specific properties
type UserPreview = Pick<User, 'id' | 'name'>

// Omit for excluding properties
type CreateUserRequest = Omit<User, 'id'>

Advanced Type Patterns

1. Generic Constraints

interface Identifiable {
  id: string
}

function updateEntity<T extends Identifiable>(
  entity: T,
  updates: Partial<T>
): T {
  return { ...entity, ...updates }
}

2. Discriminated Unions

interface LoadingState {
  status: 'loading';
}

interface SuccessState {
  status: 'success';
  data: any;
}

interface ErrorState {
  status: 'error';
  error: string;
}

type AsyncState = LoadingState | SuccessState | ErrorState;

function handleState(state: AsyncState) {
  switch (state.status) {
    case 'loading':
      return <Spinner />;
    case 'success':
      return <Data data={state.data} />;
    case 'error':
      return <Error message={state.error} />;
  }
}

3. Branded Types

type UserId = string & { __brand: 'UserId' }
type ProductId = string & { __brand: 'ProductId' }

function createUserId(id: string): UserId {
  return id as UserId
}

function getUser(id: UserId) {
  // Implementation
}

Error Handling

1. Use Result Pattern

type Result<T, E = Error> = {
  success: true
  data: T
} | {
  success: false
  error: E
}

async function fetchUser(id: string): Promise<Result<User>> {
  try {
    const user = await api.getUser(id)
    return { success: true, data: user }
  }
  catch (error) {
    return { success: false, error: error as Error }
  }
}

2. Custom Error Types

class ValidationError extends Error {
  constructor(
    message: string,
    public field: string
  ) {
    super(message)
    this.name = 'ValidationError'
  }
}

class NotFoundError extends Error {
  constructor(resource: string, id: string) {
    super(`${resource} with id ${id} not found`)
    this.name = 'NotFoundError'
  }
}

Performance Optimization

1. Use const assertions

const themes = ['light', 'dark'] as const
type Theme = typeof themes[number] // 'light' | 'dark'

const config = {
  apiUrl: 'https://api.example.com',
  timeout: 5000
} as const

2. Optimize Bundle Size

// Instead of
import _ from 'lodash'

// Use tree-shaking friendly imports
import { debounce } from 'lodash/debounce'

Testing with TypeScript

1. Type-Safe Mocks

function createMockUser(overrides?: Partial<User>): User {
  return {
    id: '1',
    name: 'John Doe',
    email: 'john@example.com',
    ...overrides
  }
}

// Usage
const user = createMockUser({ name: 'Jane Doe' })

2. Test Utilities

type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
}

function createTestData<T>(data: DeepPartial<T>): T {
  // Implementation
}

Best Practices Summary

1. Use strict TypeScript configuration
2. Prefer composition over inheritance
3. Leverage the type system for runtime safety
4. Use branded types for domain modeling
5. Implement proper error handling patterns
6. Keep types close to their usage
7. Use utility types to reduce code duplication
8. Write type-safe tests

Conclusion

TypeScript's type system is powerful, but it requires discipline and good practices to use effectively. By following these patterns and practices, you'll build more maintainable, scalable, and bug-free applications.

Remember: TypeScript is not just about adding types – it's about designing better software architecture and catching errors before they reach production.