api

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

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

File	Contents
references/principles.md	Core design and DX principles
references/typescript.md	Type inference patterns (author + consumer)
references/state.md	State management patterns and architecture
references/extensibility.md	Pipelines, builders, adapters, lifecycles
references/anti-patterns.md	Common mistakes to avoid
references/libraries.md	Reference libraries and their patterns
references/voices.md	Practitioner heuristics and reference URLs

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.

File	Contents
review/workflow.md	Review process and checklists
review/agents.md	Sub-agent prompts
review/templates.md	Issue format, report template
review/checklist.md	Quick single-agent checklist
review/example.md	Complete example review

Related Skills

Need	Use
Building UI components	component skill
Accessibility patterns	aria skill
Documentation	docs skill