Loading…

Typescript Best Practices

Production-ready TypeScript best practices — tsconfig, type patterns, generics, error handling, and code organization for strict, maintainable codebases

OpenCodeCodexClaude Code

bash

npx skills add m10rten/typescript-bits --skill typescript-best-practices

skill.md · 202 lines~1.7k

TypeScript Best Practices

Practical, production-ready TypeScript patterns for strict, maintainable codebases. Apply these when writing or reviewing TypeScript code.

Configuration

tsconfig.json — Strict Mode

Enable all strict checks — these catch real bugs at compile time:

{
  "compilerOptions": {
    // Enables all strict type-checking (noImplictAny, strictNullChecks, etc.)
    "strict": true,
    // Forces handling `undefined` from bracket access on arrays/objects
    "noUncheckedIndexedAccess": true,
    // Prevents unused variables from compiling
    "noUnusedLocals": true,
    // Prevents unused function parameters from compiling
    "noUnusedParameters": true,
    // Optional properties can't be explicitly set to `undefined`
    "exactOptionalPropertyTypes": true,
    // Enforces `import type` / `export type` — keeps runtime bundles clean
    "verbatimModuleSyntax": true
  }
}

Type System

Prefer Types Over Enums

Use `type` unions instead of `enum` — they're erasable at runtime, tree-shakeable, and compose naturally.

Use `const` objects with `as const` when you need both runtime values and type-level unions.

// Prefer this:
type Status = "active" | "inactive" | "pending";

// Over this:
enum Status {
  Active = "active",
  Inactive = "inactive",
  Pending = "pending",
}

Branded Types for Primitives

Use branded types to distinguish structurally identical primitives (e.g., two `string` IDs that must not be confused):

type UserId = string & { __brand: "UserId" };
type PostId = string & { __brand: "PostId" };

Discriminated Unions for State

Model distinct states as discriminated unions with a literal `type` or `kind` discriminant. This gives you exhaustiveness checking and narrows each branch automatically:

type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

Switch on the discriminant for narrowing & exhaustiveness:

type Shape = { kind: "circle"; radius: number } | { kind: "square"; side: number };
function area(s: Shape) {
  switch (s.kind) {
    case "circle":
      return Math.PI * s.radius ** 2;
    case "square":
      return s.side ** 2;
  }
}

Utility Types — When to Use

Type	Use case
`Pick`	Subset of known keys (stable API slice)
`Omit`	Exclude keys (e.g., strip internal fields)
`Partial`	Gradual construction / update payloads
`Required`	After validation — mark all fields as required
`Readonly`	Config objects, constants passed to consumers
`Record`	Dynamic key-value maps (use with `noUncheckedIndexedAccess`)

Advanced: Conditional Types

Use `infer` to extract unwrapped types:

type Unwrap<T> = T extends Promise<infer U> ? U : T;

Prefer `interface` for Public APIs, `type` for Computed Types

Use `interface` for object shapes that consumers implement or extend (declaration merging, better error messages).

Use `type` for unions, intersections, mapped/conditional types, tuples, and computed types.

Mapped Types for Object Transformations

Transform object types by iterating over keys:

type Nullable<T> = { [K in keyof T]: T[K] | null };
type Getters<T> = { [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K] };

Template Literal Types

Model string patterns for event names, CSS values, and API paths:

type EventName = `on${Capitalize<string>}`;
type CSSValue = `${number}${"px" | "rem"}`;

Use `satisfies` for Literal Inference

Validates a value matches a type without widening:

type Config = { url: string; retries: number };
const dev = { url: "http://localhost", retries: 3 } satisfies Config;

Generics

Constrain with `extends`: `` — never leave a generic unconstrained.

Default types reduce inference burden: ``.

Avoiding `any`

Never use `any`. It bypasses the entire type system.

Use `unknown` instead — forces runtime narrowing before use.

Use `never` for exhaustive switch/if-else checking in discriminated unions.

Use `as const` for literal inference on arrays and objects.

Error handling pattern with `unknown`:

try {
  // ...
} catch (err: unknown) {
  if (err instanceof Error) {
    console.error(err.message);
  }
}

Error Handling

Use `Result` types (discriminated union with `ok` discriminant) for expected failures — avoids try/catch control flow.

Reserve `throw` for programmer errors (assertions, invariant violations) that should crash.

Always narrow caught errors — `catch (err: unknown)` and validate shape before use.

Code Organization

No Barrel Exports

Never re-export modules through index files. Import directly from source files. This:

Prevents circular dependencies

Keeps import chains explicit and traceable

Improves tree-shaking

Self-Documenting Code

Prefer meaningful names over comments — DRY, KISS.

Write JSDoc only for: externally-exported APIs, extremely complex logic.

Skip JSDoc on internal functions — the code should speak for itself.

Module Boundaries

One module = one responsibility.

Export only what consumers need. Mark internals with `_` prefix or keep them unexported.

Type Testing and Patterns

Use assertion functions (`asserts x is T`) for runtime validation that narrows types post-return.

Write compile-time type tests using `// @ts-expect-error` for negative cases.

Avoid type assertions (`as T`) — they lie to the compiler. Use type guards instead.

Common Mistakes

Mistake	Fix
Using `any` to bypass errors	Use `unknown` + type narrowing
Overly broad return types (`object`, `Record`)	Return specific discriminated unions
Missing `readonly` on function parameters	`readonly T[]` for array params
Optional chaining on non-nullable types	Let the type system guide you — don't over-defend
Type assertions instead of type guards	Write a user-defined type guard: `x is T`