name: api description: >- API design and developer experience for TypeScript libraries. Use when designing APIs, reviewing architecture, evaluating DX, or checking ergonomics. Covers extensibility, progressive disclosure, type inference, state patterns, and composition. For review, load review/workflow.md. Triggers: "design API", "review API", "check DX", "is this ergonomic", "review architecture", "middleware design", "how does this feel".

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