TypeScript Writing Code

Quick reference for writing production-quality TypeScript code. Each section summarizes the key rules — reference files provide full examples and edge cases.

Strict TypeScript Configuration

This project enforces maximum type safety through tsconfig.base.json. Zero any tolerance — no exceptions.

Key Flags

• strict: true — Enables all strict type-checking options as a group.
• noImplicitAny: true — Every value must have an explicit or inferable type. No implicit any.
• strictNullChecks: true — null and undefined are distinct types. Must be handled explicitly.
• noUncheckedIndexedAccess: true — Array/object index access returns T | undefined. Always check before using.
• noUnusedLocals: true — Unused variables are compile errors, not warnings.
• noUnusedParameters: true — Unused function parameters are compile errors.
• noImplicitReturns: true — Every code path in a function must return a value.
• isolatedModules: true — Required for Vite/esbuild compatibility. Prevents features that need full-program analysis.

Zero any Policy

// ❌ Wrong — using `any`
function parse(data: any): User {
  return data as User;
}

// ✅ Correct — using `unknown` with narrowing
function parse(data: unknown): User {
  if (!isUser(data)) {
    throw new Error("Invalid user data");
  }
  return data;
}

Safe Indexed Access

With noUncheckedIndexedAccess, array and record access returns T | undefined:

const items = ["a", "b", "c"];
const first = items[0]; // string | undefined — must check

if (first !== undefined) {
  console.log(first.toUpperCase()); // safe
}

const map: Record<string, number> = { a: 1 };
const value = map["b"]; // number | undefined — must check

Catch Blocks

Always type catch variables as unknown:

try {
  await fetchData();
} catch (error: unknown) {
  if (error instanceof Error) {
    console.error(error.message);
  }
  throw error;
}

See references/strict-config.md for the full tsconfig.base.json, flag explanations, and anti-patterns.

Type Safety Patterns

Use TypeScript's type system to catch bugs at compile time, not runtime.

Type Guards

// typeof guard
function formatValue(value: string | number): string {
  if (typeof value === "string") {
    return value.toUpperCase();
  }
  return value.toFixed(2);
}

// Custom type guard with `is` predicate
function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "id" in value &&
    "email" in value
  );
}

Discriminated Unions

Tag union members with a literal type field. Use exhaustive switch for safety:

type Result<T> =
  | { kind: "success"; data: T }
  | { kind: "error"; error: string };

function handle<T>(result: Result<T>): void {
  switch (result.kind) {
    case "success":
      console.log(result.data);
      break;
    case "error":
      console.error(result.error);
      break;
    default: {
      const _exhaustive: never = result;
      throw new Error(`Unhandled case: ${_exhaustive}`);
    }
  }
}

Branded Types

Use branded types for nominal typing when primitive types are too loose:

type UserId = string & { readonly __brand: "UserId" };
type OrderId = string & { readonly __brand: "OrderId" };

function createUserId(id: string): UserId {
  return id as UserId;
}

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

// getUser(orderId) — compile error, even though both are strings

See references/type-safety.md for generics, utility types, assertion functions, and anti-patterns.

ESM Module Patterns

This project uses ESM ("type": "module") throughout. All packages set "type": "module" in package.json.

Import Rules

• Named exports preferred — Default exports make refactoring harder and tree-shaking less predictable.
• import type for types — Biome enforces useImportType and useExportType. Type-only imports are erased at runtime.
• node: prefix for built-ins — Always use node:path, node:fs, node:crypto.

// ✅ Correct
import { useState, useEffect } from "react";
import type { ReactNode } from "react";
import path from "node:path";

// ❌ Wrong — missing type keyword
import { ReactNode } from "react"; // Biome error: useImportType

Barrel Files

Use barrel files (index.ts) for clean public APIs, but keep them thin:

// components/index.ts
export { Button } from "./Button";
export { Input } from "./Input";
export type { ButtonProps, InputProps } from "./types";

Dynamic Imports

Use dynamic import() for code splitting in routes and heavy modules:

const AdminPanel = lazy(() => import("./pages/AdminPanel"));

See references/esm-modules.md for build output, circular dependency detection, and package.json exports.

Error Handling

Handle errors explicitly. Use result types for expected failures, exceptions for unexpected ones.

Result Type Pattern

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

function createSuccess<T>(data: T): Result<T, never> {
  return { ok: true, data };
}

function createError<E>(error: E): Result<never, E> {
  return { ok: false, error };
}

Discriminated Union Errors

type ApiError =
  | { kind: "not_found"; resource: string }
  | { kind: "validation"; fields: Record<string, string> }
  | { kind: "unauthorized" };

function handleApiError(error: ApiError): string {
  switch (error.kind) {
    case "not_found":
      return `${error.resource} not found`;
    case "validation":
      return Object.values(error.fields).join(", ");
    case "unauthorized":
      return "Please sign in";
  }
}

Try-Catch Rules

// ✅ Correct — catch unknown, narrow, add context
try {
  await api.createUser(data);
} catch (error: unknown) {
  if (error instanceof ApiError) {
    throw new Error(`Failed to create user: ${error.message}`);
  }
  throw error; // Re-throw unexpected errors
}

// ❌ Wrong — catch any, swallow error
try {
  await api.createUser(data);
} catch (e: any) {
  console.log(e.message); // unsafe access
}

See references/error-handling.md for async patterns, retry logic, and when to throw vs return errors.

Biome (Linter & Formatter)

This project uses Biome (v2.3.11) for both linting and formatting. It replaces ESLint and Prettier entirely.

Key Rules

Rule	Level	Effect
noExplicitAny	error	Cannot use any type anywhere
noUnusedVariables	error	All variables must be used
noUnusedImports	error	All imports must be used
useConst	error	Use const when variable is never reassigned
useImportType	error	Use import type for type-only imports
useExportType	error	Use export type for type-only exports
noNonNullAssertion	warn	Avoid ! postfix operator
a11y recommended	on	Accessibility rules for JSX

Formatter Settings

• Double quotes, semicolons always, trailing commas
• 2-space indent, 100-character line width
• Organize imports automatically

Commands

# Check (lint + format check)
biome check .

# Fix (lint fix + format)
biome check --write .

# CI mode (fails on any issue)
biome ci .

Critical Rule

Never add biome-ignore comments. Fix the underlying issue instead of suppressing it. This is a hard project rule — no exceptions.

See references/biome.md for the full biome.json config, VS Code integration, and common fix patterns.

Naming Conventions & Code Quality

Naming Rules

Context	Convention	Example
Variables, functions	camelCase	userName, fetchUser()
Types, interfaces, classes	PascalCase	UserProfile, AuthService
Constants	UPPER_SNAKE_CASE	MAX_RETRIES, API_BASE_URL
Files	kebab-case	user-profile.tsx, auth-service.ts
Component files	PascalCase	UserProfile.tsx, AuthGuard.tsx
Test files	Match source	UserProfile.test.tsx
Enum members	PascalCase	UserRole.Admin

Code Quality Rules

• Zero warnings policy — Treat warnings as errors. Fix them, don't ignore them.
• No @ts-ignore — Use @ts-expect-error with a comment explaining why, only as a last resort.
• No type assertions as escape hatches — as unknown as T is a code smell. Refactor instead.
• Prefer const assertions — Use as const for literal types instead of explicit type annotations.
• JSDoc for exports — Document exported functions and types with JSDoc. Focus on the "why", not the "what".

/**
 * Encrypts PII fields before database storage.
 * Uses AES-256-GCM with a per-record IV for uniqueness.
 */
export function encryptField(plaintext: string, key: Buffer): EncryptedField {
  // ...
}

Post-Change Verification (MANDATORY)

After every TypeScript code change, run this 4-step verification. No exceptions.

The 4 Steps

# 1. Type-check
pnpm run type-check
# or per-app: pnpm --filter patient type-check

# 2. Lint
pnpm run lint
# or per-app: pnpm --filter patient lint

# 3. Format
pnpm run format
# or per-app: pnpm --filter patient format

# 4. Test
pnpm run test
# or per-app: pnpm --filter patient test

One-Command Verification

# Run all checks for a specific app
pnpm --filter patient validate

Rules

• All 4 steps must pass before considering a change complete.
• Fix issues immediately — Don't defer lint warnings or type errors.
• Never suppress to pass — No @ts-ignore, no biome-ignore, no any casts.

See references/post-change-protocol.md for the full verification workflow, common failures, and troubleshooting.

Reference Files

File	Description
references/strict-config.md	Full tsconfig.base.json, strict flags, zero-any patterns, anti-patterns
references/type-safety.md	Type guards, discriminated unions, branded types, generics, utility types
references/esm-modules.md	ESM fundamentals, import/export rules, barrel files, build output
references/error-handling.md	Result types, discriminated union errors, async patterns, retry logic
references/biome.md	Full biome.json config, rules reference, VS Code integration
references/post-change-protocol.md	4-step verification workflow, troubleshooting, common failures