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