TypeScript Best Practices for Large Codebases

Why TypeScript at Scale

TypeScript becomes increasingly valuable as codebases grow. But without proper practices, you can end up with thousands of any types and lose most benefits.

Enable Strict Mode

Start every project with strict mode:

{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true
}
}

Discriminated Unions Over Optional Properties

Instead of:

interface ApiResponse {
data?: User;
error?: string;
loading?: boolean;
}

Use discriminated unions:

type ApiResponse =
| { status: "loading" }
| { status: "success"; data: User }
| { status: "error"; error: string };
function handleResponse(response: ApiResponse) {
switch (response.status) {
case "loading":
return <Spinner />;
case "success":
return <UserCard user={response.data} />;
case "error":
return <Error message={response.error} />;
}
}

Leverage Type Inference

Let TypeScript work for you:

// Avoid: Redundant type annotation
const users: User[] = fetchUsers();
// Prefer: Let inference handle it
const users = fetchUsers(); // Type is inferred

Utility Types Are Your Friends

Master the built-in utility types:

// Pick specific properties
type UserPreview = Pick<User, "id" | "name" | "avatar">;
// Make all properties optional
type PartialUser = Partial<User>;
// Make all properties required
type RequiredUser = Required<User>;
// Extract return type of a function
type FetchResult = ReturnType<typeof fetchUser>;

Branded Types for Domain Safety

Prevent mixing up primitive types:

type UserId = string & { readonly brand: unique symbol };
type OrderId = string & { readonly brand: unique symbol };
function createUserId(id: string): UserId {
return id as UserId;
}
function getUser(id: UserId) { / ... / }
const userId = createUserId("123");
const orderId = createOrderId("456");
getUser(userId);  // OK
getUser(orderId); // Error!

Conclusion

TypeScript is only as good as the types you write. Invest in your type definitions and they will pay dividends in bug prevention and developer experience.