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:
- Correctness — wrong behavior > verbose API
- Type Safety — inference failures > extra generics
- Simplicity — fewer concepts > fewer keystrokes
- Consistency — match existing codebase patterns
- Bundle Size — tree-shaking matters, but not at DX cost
Anti-Patterns
| Anti-Pattern |
Why It Fails |
| Function overloads |
Poor errors, autocomplete confusion |
| Runtime plugin registration |
Loses type safety, implicit ordering |
| Positional parameters (3+) |
Order confusion, breaking changes |
| Implicit contracts |
Silent breakage when requirements unmet |
| Per-module middleware |
Unexpected interactions |
| Shotgun parsing |
Validation scattered, not at boundaries |
| Boolean traps |
fn(true, false) — what do these mean? |
| Multiple competing APIs |
Confusing — which method to use? |
Reference Files
Loading by Domain
| Domain |
Load |
| General API work |
principles.md |
| TypeScript/types |
typescript.md |
| State management |
state.md |
| Middleware/plugins |
extensibility.md |
| Avoiding mistakes |
anti-patterns.md |
| Library comparisons |
libraries.md, voices.md |
Review
For reviewing APIs and architecture, load review/workflow.md.
Related Skills
| Need |
Use |
| Building UI components |
component skill |
| Accessibility patterns |
aria skill |
| Documentation |
docs skill |