typescript-craftsmanship

TypeScript Craftsmanship

This skill enforces professional-grade TypeScript, React 19, and Next.js 15 coding standards. Every piece of code you write or review must pass these rules.

The philosophy: make invalid states unrepresentable, make expensive operations obvious, and make the code read like well-written prose.

When writing complex logic, refactoring, or doing architecture work, load the appropriate reference file for deeper patterns:

• references/design-patterns.md — SOLID principles, GoF patterns adapted to TS/React, anti-patterns to avoid. Read this before any refactoring session or when designing new modules/components.
• references/algorithms.md — Complexity analysis, data structure choices, performance patterns. Read this when optimizing, writing data transforms, or working with collections/arrays.
• references/react-architecture.md — React 19, Next.js 15 App Router, Zustand, TanStack Query, state management patterns. Read this when creating components, hooks, stores, or page layouts.

---

Core Rules — Always Active

These rules apply to every line of TypeScript you write. No exceptions.

1. Type Safety is Non-Negotiable

Zero any. Use unknown + type guards. If you think you need any, you need a generic or a discriminated union.

// ❌ Lazy typing
function process(data: any) {
  return data.name;
}

// ✅ Safe typing
function process(data: unknown): string {
  if (isUser(data)) return data.name;
  throw new TypeError("Expected User object");
}

Zero type assertions (as). They lie to the compiler. Use type guards, discriminated unions, or Zod parsing instead.

// ❌ Assertion — compiles but crashes if wrong
const user = response.data as User;

// ✅ Runtime validation
const user = UserSchema.parse(response.data); // Zod: throws if invalid

Zero non-null assertions (!). Use optional chaining + nullish coalescing.

// ❌ Crashes at runtime if null
const name = user!.name;

// ✅ Safe access
const name = user?.name ?? "Anonymous";