TypeScript Best Practices

TypeScript has become the de‑facto standard for building large‑scale JavaScript applications, and for good reason. It adds a robust type system, powerful tooling, and early error detection without sacrificing the flexibility of JavaScript. In this guide we’ll walk through the most effective practices that help you write clean, maintainable, and scalable TypeScript code.

Project Setup and Configuration

Start every new project with a well‑crafted tsconfig.json. This file is the single source of truth for the compiler, and a solid baseline prevents many headaches later on. Enable strict mode, target modern JavaScript, and configure module resolution to match your bundler.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Node",
    "strict": true,
    "noImplicitAny": true,
    "forceConsistentCasingInFileNames": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "sourceMap": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

Keep the configuration under version control and treat it like any other source file. When you add new libraries or change build targets, update the config first, then adjust the code. This approach ensures that the compiler’s expectations are always aligned with the actual runtime environment.

Pro tip: Use extends in tsconfig.json to share a base configuration across multiple packages in a monorepo. It reduces duplication and guarantees consistency.

Embrace Strict Types Everywhere

Strict mode is not optional—it’s the foundation of reliable TypeScript code. It forces you to annotate function parameters, return types, and object shapes, which eliminates the “any” creep that often sneaks into large codebases.

When you encounter a third‑party library without types, create a minimal declaration file that captures only the parts you use. This keeps the type surface small and easy to maintain.

// types/my-lib.d.ts
declare module "my-lib" {
  export function fetchData(url: string): Promise<any>;
}

Later, as the library evolves, you can replace the stub with the official typings or a more complete custom definition. The key is to avoid falling back to any as a shortcut.

Design Clear Interfaces and Types

Interfaces and type aliases are the building blocks of a well‑structured codebase. Use them to describe data contracts, API payloads, and component props. Prefer interfaces for object shapes that may be extended, and type aliases for unions or primitive transformations.

// src/models/user.ts
export interface User {
  id: string;
  name: string;
  email: string;
  role: "admin" | "editor" | "viewer";
  createdAt: Date;
}

When you need a read‑only version of an object, wrap the interface with the built‑in Readonly utility. This signals intent and prevents accidental mutation.

export type ReadonlyUser = Readonly<User>;

Pro tip: Keep interfaces close to where they are used. If a type is only relevant to a single module, define it there instead of a global types folder.

Leverage Generics for Reusability

Generics allow you to write functions and classes that work with a variety of types while preserving type safety. They are especially useful for data fetching utilities, collection helpers, and component libraries.

// src/utils/fetch.ts
export async function fetchJson<T>(url: string): Promise<T> {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Failed to fetch ${url}`);
  }
  return (await response.json()) as T;
}

When you call fetchJson, you specify the expected shape, and TypeScript will enforce it throughout the consuming code.

// usage
interface Post {
  id: number;
  title: string;
  body: string;
}

const post = await fetchJson<Post>("/api/posts/1");
console.log(post.title); // ✅ type‑checked

Prefer Union Types Over Enums When Possible

String literal unions give you the same expressive power as enums while producing cleaner JavaScript output. They also integrate seamlessly with autocomplete and exhaustive checks.

type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";

function request(method: HttpMethod, url: string) {
  // implementation
}

If you need a numeric mapping or want to iterate over values, a traditional enum still makes sense. Choose the tool that matches the use case, not the other way around.

Utilize Built‑In Utility Types

TypeScript ships with a suite of utility types—Partial, Pick, Omit, Record, and more. These helpers let you transform existing types without redefining them.

// src/services/userService.ts
import { User } from "../models/user";

export type UpdateUserPayload = Partial<Pick<User, "name" | "email">>;

export async function updateUser(id: string, data: UpdateUserPayload) {
  // send PATCH request
}

In the example above, UpdateUserPayload only allows the mutable fields and makes them optional, mirroring a typical PATCH endpoint.

Pro tip: Combine Required<T> with Pick to enforce that certain fields are always present in a subset of a larger type.

Integrate Seamlessly with Third‑Party Libraries

Most popular libraries provide official type definitions, but when they don’t, use declare module or the @types community packages. Always import types explicitly to avoid accidental global pollution.

// src/hooks/useAxios.ts
import axios, { AxiosResponse } from "axios";

export function useAxios<T>(url: string): Promise<AxiosResponse<T>> {
  return axios.get<T>(url);
}

Notice how the generic T flows from the hook to the Axios response, giving callers full type safety without extra boilerplate.

Write Testable, Refactor‑Friendly Code

Strong typing reduces runtime bugs, but unit tests still catch logical errors. Use ts-jest or vitest to run tests directly on TypeScript files, preserving type information during the test run.

// src/utils/math.test.ts
import { add } from "./math";

test("adds two numbers", () => {
  expect(add(2, 3)).toBe(5);
});

When refactoring, rely on the compiler’s “find all references” and “rename symbol” features. They work best when every exported symbol has a clear, explicit type.

Pro tip: Enable noUnusedLocals and noUnusedParameters in tsconfig. Unused code is a strong indicator of dead paths that can be safely removed.

Optimize Build and Runtime Performance

TypeScript itself does not affect runtime speed, but the way you emit code can. Target modern JavaScript (ES2022+) to let browsers handle native features like async/await and optional chaining without polyfills.

For library authors, ship both .d.ts declaration files and compiled JavaScript, and provide a typesVersions field if you support multiple TypeScript versions. This ensures downstream projects get accurate typings without extra build steps.

Adopt Consistent Coding Conventions

Consistency is half the battle. Use a linter such as eslint with the @typescript-eslint plugin, and enforce rules for naming, import ordering, and explicit return types. Pair the linter with prettier to automatically format code on save.

// .eslintrc.js
module.exports = {
  parser: "@typescript-eslint/parser",
  plugins: ["@typescript-eslint"],
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "prettier"
  ],
  rules: {
    "@typescript-eslint/explicit-function-return-type": "warn",
    "@typescript-eslint/no-explicit-any": "error"
  }
};

When the team follows the same rule set, code reviews become faster, and the codebase stays predictable as it grows.

Real‑World Use Cases

Feature flag system. By modeling flags as a union of string literals, you can guarantee that only known flags are used throughout the app.

type FeatureFlag = "betaSearch" | "newDashboard" | "darkMode";

interface FlagConfig {
  [key in FeatureFlag]: boolean;
}

const flags: FlagConfig = {
  betaSearch: false,
  newDashboard: true,
  darkMode: false
};

function isFeatureEnabled(flag: FeatureFlag): boolean {
  return flags[flag];
}

This pattern eliminates magic strings and makes toggling features type‑safe.

Domain‑driven design with value objects. Wrap primitive values in branded types to prevent accidental mix‑ups, such as using a user ID where a product ID is expected.

type Brand<T, B> = T & { __brand: B };

type UserId = Brand<string, "UserId">;
type ProductId = Brand<string, "ProductId">;

function getUser(id: UserId) {/* ... */}
function getProduct(id: ProductId) {/* ... */}

const uid = "u123" as UserId;
const pid = "p456" as ProductId;

getUser(uid);      // ✅
getUser(pid);      // ❌ TypeScript error

Branded types add zero runtime overhead while providing a strong compile‑time guarantee.

Conclusion

Adopting these best practices turns TypeScript from a optional add‑on into a strategic asset for your projects. Strong typing, disciplined configuration, and consistent tooling together create a feedback loop that catches bugs early, clarifies intent, and speeds up development. By treating types as contracts rather than afterthoughts, you’ll write code that scales gracefully, ships faster, and remains a joy to maintain.