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 |
