API Design & Developer Experience

Principles for designing TypeScript library APIs and evaluating developer experience.

Goal: APIs should feel obvious, fast, safe, and composable — with great defaults and great escape hatches.

Quick Reference

Foundational

• Emergent extensibility — Best extension points look like well-designed APIs, not plugin systems
• Composition over configuration — devtools(persist(fn)) beats { middlewares: [] }
• Onion model — Transformative middleware innermost, observational outermost

API Surface

• Config objects for 3+ parameters (no overloads)
• Flat returns for independent values, namespaced for cohesive units
• Rule of two — Tuples for 2 values, objects for 3+
• Inference over annotation — If users annotate, types aren't flowing

Progressive Disclosure

• Complexity grows with use case — Zero-config → Options → Composition → Headless → Core
• Escape hatches compose — Don't require reimplementing defaults
• Explicit contracts — Render props over implicit requirements

Developer Experience

• Time-to-first-success — Minimize time from install to working code
• Cognitive load — Fewer concepts > fewer keystrokes
• Predictable outcomes — Match user mental models
• Editor ergonomics — TypeScript inference should just work

Conflict Resolution

When principles conflict, prioritize:

1. Correctness — wrong behavior > verbose API
2. Type Safety — inference failures > extra generics
3. Simplicity — fewer concepts > fewer keystrokes
4. Consistency — match existing codebase patterns
5. Bundle Size — tree-shaking matters, but not at DX cost

Anti-Patterns

Reference Files

Loading by Domain

Review

For reviewing APIs and architecture, load review/workflow.md.

Related Skills