koa
Koa.js web framework. Use when building Node.js APIs with async middleware, koa-router, context object, error handling, body parsing, or CORS. Distinguish from Express when user needs modern async pat
SKILL.mdconfig/skills/koa/SKILL.md
GitHubkoa
Lightweight Node.js framework by Express team using async/await middleware and enhanced context.
Core Concepts
- Async middleware:
app.use(async (ctx, next) => { ... })with upstream/downstream execution via await next() - Context object:
ctxwraps Nodereq/reswith helpers for body, params, cookies, and state - Koa vs Express: no built-in routing, no middleware in req/res, no callback-based middleware
- Error handling: centralized
app.on('error')listener or try/catch in async middleware
Common Patterns
- koa-router:
router.get('/users/:id', handler)with named params, nested routers, and HTTP verb methods - Body parsing:
@koa/bodyparserfor JSON, form, and text payloads - CORS:
@koa/corsmiddleware with origin whitelist and credential support - Static files:
@koa/staticfor serving assets with caching headers
Best Practices
- Top-level error middleware wrapping all downstream handlers with try/catch and structured JSON errors
ctx.statefor passing request-scoped data (auth user, request ID) between middleware- Composition over mounting: compose small middleware functions rather than monolithic handlers
- Supertest with jest/ava for HTTP integration tests without binding to a port
Common Code Patterns
ctx.body = { data: result }for JSON responses with automatic content-typectx.throw(400, 'validation failed')for HTTP error responses with message