TypeScript Best Practices for Large Codebases

TypeScript has become the de facto standard for building scalable JavaScript applications. But simply adding .ts to your file extensions isn't enough to reap its full benefits. After working with TypeScript in production environments for several years, I've compiled the practices that actually make a difference in code quality and team productivity.

1. Enable Strict Mode from Day One

The biggest mistake teams make is being too permissive with their TypeScript configuration. Your tsconfig.json should have strict mode enabled:

          {
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "exactOptionalPropertyTypes": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}
        

Why strict mode matters: It forces you to handle edge cases that would otherwise cause runtime errors. strictNullChecks alone catches countless Cannot read property of null errors.

2. Use Discriminated Unions for Complex State

Instead of boolean flags scattered across your state, use discriminated unions. They're self-documenting and make impossible states unrepresentable:

          // X Bad: Multiple boolean flags
type DataState = {
  data: User | null;
  isLoading: boolean;
  isError: boolean;
  error: Error | null;
};

// OK Good: Discriminated union
type DataState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: User }
  | { status: 'error'; error: Error };

// Usage in component
function UserProfile({ state }: { state: DataState }) {
  switch (state.status) {
    case 'idle':
      return <p>Click to load user</p>;
    case 'loading':
      return <Spinner />;
    case 'success':
      return <UserCard user={state.data} />; // TypeScript knows data exists
    case 'error':
      return <ErrorMessage error={state.error} />; // TypeScript knows error exists
  }
}
        

3. Leverage Type Inference, But Be Explicit Where It Matters

TypeScript's inference is excellent—don't fight it by adding redundant type annotations. But be explicit in public APIs and complex functions:

          // OK Good: Let TypeScript infer simple cases
const userCount = 42; // inferred as number
const userName = 'Alice'; // inferred as string

// OK Good: Be explicit for function returns
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// OK Good: Explicit types for public API interfaces
export interface UserService {
  getUser(id: string): Promise<User>;
  updateUser(id: string, updates: UserUpdates): Promise<User>;
  deleteUser(id: string): Promise<void>;
}

// X Bad: Redundant annotations
const count: number = 42;
const name: string = 'Alice';
        

4. Use Type Guards for Runtime Safety

Type guards are functions that narrow types at runtime. They're essential when dealing with union types or external data:

          // Type guard function
function isError(response: unknown): response is ErrorResponse {
  return (
    typeof response === 'object' &&
    response !== null &&
    'error' in response &&
    typeof (response as ErrorResponse).error === 'string'
  );
}

// Usage
async function fetchUser(id: string): Promise<User> {
  const response = await api.get(\`/users/\${id}\`);
  
  if (isError(response)) {
    throw new Error(response.error); // TypeScript knows this is ErrorResponse
  }
  
  return response; // TypeScript knows this is User
}

// Built-in type guards
type Status = 'loading' | 'success' | 'error';

function isValidStatus(value: unknown): value is Status {
  return ['loading', 'success', 'error'].includes(value as string);
}
        

5. Master Generics for Reusable Code

Generics allow you to write flexible, reusable components and functions while maintaining type safety:

          // Generic API client
async function fetchApi<T>(url: string): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(\`HTTP error! status: \${response.status}\`);
  }
  return response.json() as Promise<T>;
}

// Usage with automatic type inference
const user = await fetchApi<User>('/api/user/123');
const posts = await fetchApi<Post[]>('/api/posts');

// Generic React component
interface ListProps<T> {
  items: T[];
  renderItem: (item: T) => React.ReactNode;
  keyExtractor: (item: T) => string;
}

function List<T>({ items, renderItem, keyExtractor }: ListProps<T>) {
  return (
    <ul>
      {items.map(item => (
        <li key={keyExtractor(item)}>{renderItem(item)}</li>
      ))}
    </ul>
  );
}

// Usage
<List
  items={users}
  renderItem={user => <UserCard user={user} />}
  keyExtractor={user => user.id}
/>
        

6. Use Branded Types for Type-Safe IDs

Prevent mixing up different ID types with branded types. This catches bugs at compile time:

          // Create branded types
type UserId = string & { readonly __brand: unique symbol };
type PostId = string & { readonly __brand: unique symbol };
type CommentId = string & { readonly __brand: unique symbol };

// Factory functions for creation
function createUserId(id: string): UserId {
  return id as UserId;
}

function createPostId(id: string): PostId {
  return id as PostId;
}

// Now TypeScript prevents mixups
function getUser(id: UserId) 
function getPost(id: PostId) 

const userId = createUserId('123');
const postId = createPostId('456');

getUser(userId); // OK Works
getUser(postId); // X Error: Argument of type 'PostId' is not assignable to parameter of type 'UserId'
        

7. Avoid any Like the Plague

Using any defeats the purpose of TypeScript. When you need flexibility, use these alternatives:

• unknown - Use when you genuinely don't know the type. Forces type checking before use.
• Record<string, unknown> - For objects with unknown structure.
• Generics - For functions that work with multiple types.

          // X Bad
function parseData(input: any): any {
  return JSON.parse(input);
}

// OK Good
function parseData<T>(input: string): T {
  return JSON.parse(input) as T;
}

// OK Good for truly unknown data
function processExternalData(data: unknown): void {
  if (typeof data === 'object' && data !== null) {
    // Safe to proceed with type guards
  }
}
        

Conclusion: Consistency is Key

These practices only work if your whole team follows them. Set up ESLint rules to enforce your standards, and include type safety in your code review checklist. The initial investment pays off with fewer bugs, easier refactoring, and more confident deployments.

Start with strict mode and discriminated unions—they provide the most immediate value. As your team gets comfortable, gradually introduce more advanced patterns like branded types and sophisticated generics.