typescript-strict

TypeScript Strict Mode

Catch errors at build time, not in production.

When to Use This Skill

• Starting a new TypeScript project
• Tightening an existing codebase
• Preventing any types from leaking through
• Want compile-time guarantees for runtime safety

Core Concepts

1. Strict mode - Enables all strict type checks
2. Index safety - Array access returns T | undefined
3. Exhaustiveness - Compiler ensures all cases handled
4. Branded types - Prevent mixing up IDs and primitives

TypeScript Implementation

tsconfig.json (Strict Configuration)

{
  "compilerOptions": {
    // Target modern JS
    "target": "ES2022",
    "lib": ["ES2022"],
    "module": "ESNext",
    "moduleResolution": "bundler",
    
    // STRICT MODE - The important part
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "exactOptionalPropertyTypes": true,
    
    // Additional safety
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    
    // Interop
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    
    // Output
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true
  }
}

What Each Flag Does

Path Aliases

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/lib/*": ["./src/lib/*"],
      "@/types/*": ["./src/types/*"]
    }
  }
}

// Before (fragile)
import { Button } from '../../../components/ui/Button';

// After (clean)
import { Button } from '@/components/ui/Button';

Type Patterns

Branded Types (Prevent ID Mixups)

// types/branded.ts
declare const brand: unique symbol;

type Brand<T, B> = T & { [brand]: B };

export type UserId = Brand<string, 'UserId'>;
export type OrderId = Brand<string, 'OrderId'>;
export type ProductId = Brand<string, 'ProductId'>;

// Helper to create branded values
export const UserId = (id: string) => id as UserId;
export const OrderId = (id: string) => id as OrderId;

// Usage - compiler prevents mixing IDs
function getOrder(id: OrderId): Promise<Order>;
function getUser(id: UserId): Promise<User>;

const userId = UserId('user_123');
const orderId = OrderId('order_456');

getUser(userId);   // ✅ OK
getOrder(orderId); // ✅ OK
getOrder(userId);  // ❌ Type error! Can't use UserId as OrderId

Exhaustive Switch

// Ensure all enum cases handled
type Status = 'pending' | 'active' | 'completed' | 'failed';

function getStatusColor(status: Status): string {
  switch (status) {
    case 'pending':
      return 'yellow';
    case 'active':
      return 'blue';
    case 'completed':
      return 'green';
    case 'failed':
      return 'red';
    default:
      // This line ensures exhaustiveness
      const _exhaustive: never = status;
      throw new Error(`Unhandled status: ${_exhaustive}`);
  }
}

// If you add a new status, TypeScript will error until you handle it

Result Type (No Exceptions)

// types/result.ts
export type Result<T, E = Error> = 
  | { ok: true; value: T }
  | { ok: false; error: E };

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

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

// Usage
type FetchError = 'NOT_FOUND' | 'NETWORK_ERROR' | 'UNAUTHORIZED';

async function fetchUser(id: string): Promise<Result<User, FetchError>> {
  try {
    const response = await fetch(`/api/users/${id}`);
    
    if (response.status === 404) return err('NOT_FOUND');
    if (response.status === 401) return err('UNAUTHORIZED');
    if (!response.ok) return err('NETWORK_ERROR');
    
    const user = await response.json();
    return ok(user);
  } catch {
    return err('NETWORK_ERROR');
  }
}

// Caller must handle both cases
const result = await fetchUser('123');

if (!result.ok) {
  // TypeScript knows: result.error is FetchError
  switch (result.error) {
    case 'NOT_FOUND':
      return notFound();
    case 'UNAUTHORIZED':
      return redirect('/login');
    case 'NETWORK_ERROR':
      return serverError();
  }
}

// TypeScript knows: result.value is User
console.log(result.value.name);

Type Guards

// Type guard function
function isUser(value: unknown): value is User {
  return (
    typeof value === 'object' &&
    value !== null &&
    'id' in value &&
    'email' in value &&
    typeof (value as User).id === 'string' &&
    typeof (value as User).email === 'string'
  );
}

// Usage with unknown data
function handleWebhook(body: unknown) {
  if (isUser(body)) {
    // TypeScript knows body is User here
    console.log(body.email);
  }
}

Zod for Runtime Validation

// schemas/user.ts
import { z } from 'zod';

export const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string().min(1).max(100),
  role: z.enum(['admin', 'user', 'guest']),
  createdAt: z.string().datetime(),
});

// Infer TypeScript type from schema
export type User = z.infer<typeof UserSchema>;

// Validate external data
function handleWebhook(body: unknown): User {
  return UserSchema.parse(body); // Throws ZodError if invalid
}

// Safe parse (no throw)
const result = UserSchema.safeParse(body);
if (!result.success) {
  console.error(result.error.issues);
  return;
}
// result.data is User

Common Strict Mode Fixes

Fix 1: Array Index Access

// ❌ Error with noUncheckedIndexedAccess
const items = ['a', 'b', 'c'];
const first = items[0].toUpperCase(); // items[0] is string | undefined

// ✅ Fix: Optional chaining
const first = items[0]?.toUpperCase();

// ✅ Fix: Check first
const first = items[0];
if (first) {
  console.log(first.toUpperCase());
}

// ✅ Fix: Non-null assertion (when you're certain)
const first = items[0]!.toUpperCase();

// ✅ Fix: Use .at() with check
const first = items.at(0);
if (first !== undefined) {
  console.log(first.toUpperCase());
}

Fix 2: Optional Properties

// ❌ Error with exactOptionalPropertyTypes
interface Config {
  timeout?: number;
}
const config: Config = { timeout: undefined }; // Error!

// ✅ Fix: Omit the property
const config: Config = {};

// ✅ Fix: Explicitly allow undefined
interface Config {
  timeout?: number | undefined;
}

Fix 3: Object Index Signature

// ❌ Error with noPropertyAccessFromIndexSignature
interface Cache {
  [key: string]: string;
}
const cache: Cache = {};
const value = cache.someKey; // Error: use bracket notation

// ✅ Fix: Use bracket notation
const value = cache['someKey'];

Fix 4: Override Keyword

// ❌ Error with noImplicitOverride
class Animal {
  speak() { console.log('...'); }
}

class Dog extends Animal {
  speak() { console.log('Woof!'); } // Error: missing override
}

// ✅ Fix: Add override keyword
class Dog extends Animal {
  override speak() { console.log('Woof!'); }
}

Best Practices

1. Start strict - Enable strict mode from day one
2. No any - Use unknown + type guards instead
3. Validate boundaries - Use Zod for external data (API, forms)
4. Branded types - Prevent ID mixups in domain logic
5. Result types - Make error handling explicit

Common Mistakes

• Using any to silence errors (use unknown instead)
• Ignoring noUncheckedIndexedAccess warnings
• Not validating data at system boundaries
• Mixing up IDs without branded types
• Using ! non-null assertion without certainty

Related Skills

• Environment Config
• Request Validation
• Error Handling