TypeScript Best Practices: 8 Rules with Before and After

The rules below are the ones that prevent the most bugs in real TypeScript code. Each shows the common version first and the better one second, in code you can run. The first rule matters most: stop using any.

Use unknown Instead of any

any switches off type checking for a value and for everything computed from it. unknown also accepts any value, but you have to check it before using it, which puts the check where the data enters your program:

// Before: any switches off checking for everything it touches.
function totalAny(items: any): number {
  return items.reduce((sum: number, item: any) => sum + item.price, 0);
}
console.log(totalAny([{ price: 2 }, { cost: 3 }])); // NaN, no error anywhere

// After: take unknown, check once at the boundary, then work with real types.
interface Item {
  price: number;
}

function isItems(value: unknown): value is Item[] {
  return Array.isArray(value) && value.every((i) => typeof i?.price === "number");
}

function total(input: unknown): number {
  if (!isItems(input)) throw new Error("Expected a list of items with prices");
  return input.reduce((sum, item) => sum + item.price, 0);
}

console.log(total([{ price: 2 }, { price: 3 }])); // 5
try {
  total([{ price: 2 }, { cost: 3 }]);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Expected a list of items with prices
}

The boundaries are the places where types stop being guaranteed: JSON.parse, fetch responses, localStorage, form input, environment variables and messages from other processes. Validate there with a type guard or a schema library, and the rest of the code can trust its types.

Keep strict On

strict is the default in TypeScript 7; do not turn it off. Add the checks it leaves out that catch the most bugs:

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

noUncheckedIndexedAccess makes arr[i] and record[key] include undefined, which is what they return for a missing index. noImplicitOverride makes a subclass method say override, and noFallthroughCasesInSwitch rejects a case that runs into the next one.

Let Inference Work

Annotate what TypeScript cannot know: function parameters, and the return types of functions other modules use. Leave local variables and callback parameters to inference. An unneeded annotation is not only noise; it can make a type wider than the value:

type Status = "active" | "banned";

function setStatus(status: Status): string {
  return `status set to ${status}`;
}

const annotated: string = "active"; // annotation widens the type to string
// @ts-expect-error string is not assignable to Status
setStatus(annotated);

const inferred = "active"; // inferred as the literal type "active"
console.log(setStatus(inferred)); // status set to active

const users = [{ id: 1, name: "Ada" }, { id: 2, name: "Lin" }];
const ids = users.map((u) => u.id); // inferred: number[]
console.log(ids); // [ 1, 2 ]

Without the @ts-expect-error comment, setStatus(annotated) is error TS2345. The inferred const keeps the literal type "active", so it is accepted. Hover a variable in your editor to see what was inferred before you add a type.

Prefer Union Types to Enums

A union of string literals gives autocomplete and exhaustive checks with no generated code. When you also need the list of values at run time, derive the type from an as const array:

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function canEdit(role: Role): boolean {
  return role !== "viewer";
}

console.log(canEdit("editor"));     // true
console.log(ROLES.filter(canEdit)); // [ 'admin', 'editor' ]

canEdit("owner"); // error TS2345: Argument of type '"owner"' is not assignable to parameter of type '"admin" | "editor" | "viewer"'.

An enum Role { Admin, Viewer } compiles to an object with a reverse mapping, and a numeric enum parameter accepts any number variable, even one holding a value the enum does not list. Enums also cannot run under Node's type stripping (TypeScript enum is not supported in strip-only mode). The trade-offs are compared on the enums page.

Check Config Objects with satisfies

Annotating an object with a wide type like Record<string, Route> checks its values but forgets its keys. satisfies checks the same thing and keeps the exact type:

interface Route {
  path: string;
  auth: boolean;
}

// Annotated: every string key is allowed, so typos are not caught.
const loose: Record<string, Route> = {
  home: { path: "/", auth: false },
};
console.log(loose.hmoe); // undefined, and no compile error

// satisfies: checked against Route, but the exact keys are kept.
const routes = {
  home: { path: "/", auth: false },
  admin: { path: "/admin", auth: true },
} satisfies Record<string, Route>;

console.log(routes.admin.path); // /admin
// @ts-expect-error Property 'hmoe' does not exist
routes.hmoe;

Use an annotation when the variable should have exactly the declared type (a function parameter, a value you will reassign). Use satisfies for lookup tables, route maps, theme tokens and other constant objects.

Model State with Discriminated Unions

A single object with optional fields allows states that cannot happen: loading: true together with an error, or data missing after success. A union of objects with a shared tag allows only the real states, and each branch sees only its own fields:

type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "error"; message: string };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", "); // data exists only here
    case "error":
      return `Error: ${state.message}`;
    default: {
      const unreachable: never = state; // fails if a case is missing
      return unreachable;
    }
  }
}

console.log(render({ status: "success", data: ["a", "b"] })); // a, b
console.log(render({ status: "error", message: "timeout" }));  // Error: timeout

The never line is the exhaustive check. When someone adds a state and forgets to handle it, the build breaks at that line:

// This does not compile: a new state was added but not handled.
type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "cancelled" };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", ");
    default: {
      const unreachable: never = state;
      return unreachable;
    }
  }
}

console.log(render({ status: "loading" }));

The error is index.ts(14,13): error TS2322: Type '{ status: "cancelled"; }' is not assignable to type 'never'. It names the unhandled case. Add case "cancelled": and it compiles.

Avoid ! and as

The non-null assertion x! and the type assertion x as T tell the compiler to stop checking. Neither changes the value at run time, so a wrong assertion becomes a crash later, far from its cause:

interface User {
  name: string;
}

const users = new Map<string, User>([["ada", { name: "Ada" }]]);

// Before: ! and as silence the compiler, and the crash moves to run time.
try {
  console.log(users.get("bob")!.name);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Cannot read properties of undefined (reading 'name')
}
const fake = {} as User;
console.log(fake.name); // undefined, typed as string

// After: handle the missing case where it can happen.
const bob = users.get("bob");
console.log(bob?.name ?? "unknown user"); // unknown user

Replace ! with ?., ??, an early return, or a thrown error with a useful message. Replace as with a type guard that actually tests the value. The one assertion that is always safe is as const, because it only makes a type narrower and read-only. A good lint setup (typescript-eslint's no-non-null-assertion and no-explicit-any) flags the rest.

Make Data readonly

Mark properties and arrays readonly when code should not change them. The compiler then rejects push, sort and assignments, and functions return new values instead of mutating their inputs:

interface Settings {
  readonly theme: "light" | "dark";
  readonly tags: readonly string[];
}

function withTag(settings: Settings, tag: string): Settings {
  // settings.tags.push(tag) would not compile
  return { ...settings, tags: [...settings.tags, tag] };
}

const before: Settings = { theme: "dark", tags: ["a"] };
const after = withTag(before, "b");
console.log(before.tags, after.tags); // [ 'a' ] [ 'a', 'b' ]

// @ts-expect-error Cannot assign to 'theme' because it is a read-only property.
before.theme = "light";

readonly is checked only at compile time and only one level deep: it does not freeze the object at run time. That is still enough to catch the accidental mutation of shared state that causes most of these bugs.