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.md

GitHub

koa

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: ctx wraps Node req/res with 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/bodyparser for JSON, form, and text payloads
  • CORS: @koa/cors middleware with origin whitelist and credential support
  • Static files: @koa/static for serving assets with caching headers

Best Practices

  • Top-level error middleware wrapping all downstream handlers with try/catch and structured JSON errors
  • ctx.state for 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-type
  • ctx.throw(400, 'validation failed') for HTTP error responses with message