Koa

Koa is a web application framework built by the same team behind Express, designed to be a smaller, more expressive, and more robust foundation for web applications and APIs. Its middleware stack uses async functions almost exclusively, replacing callback pyramids with a stack-like flow: middleware runs downstream to the next handler, then unwinds back upstream, letting each layer manipulate the response after the handlers beneath it have run.

Koa ships with no bundled middleware — no router, no body parser, no templating engine. Instead it exposes a small, well-designed core (an Application, and Context, Request, and Response objects that delegate to Node’s native http primitives) and lets the ecosystem (koa-router, koa-bodyparser, koa-static, and dozens of others) supply everything else. This keeps the core codebase compact and auditable while still enabling a full-featured HTTP server through composition.

What You Get

• A minimal Application class exposing use(), listen(), and callback() for wiring middleware into Node’s native HTTP server
• Unified Context object delegating to Request and Response helpers for headers, cookies, content negotiation, and streaming bodies
• Cascading async middleware composition via koa-compose, so downstream and upstream logic share one function signature
• Centralized error handling through ctx.throw() and an app-level error event, translating thrown errors into HTTP responses via http-errors
• Optional AsyncLocalStorage-backed request context (app.currentContext) for accessing the active context outside the middleware chain
• A large ecosystem of community middleware (routers, body parsers, static file servers, session stores) since none is bundled by default

Common Use Cases

• Building REST or GraphQL APIs where async/await-based middleware keeps request handlers linear and readable
• Assembling a custom web server from small, individually chosen middleware packages instead of a batteries-included framework
• Migrating from Express when a team wants explicit control over error handling and response flow instead of implicit callback-based middleware
• Serving as the HTTP layer underneath higher-level frameworks and platforms that need a lightweight, well-tested request/response abstraction

Under The Hood

Architecture

Koa’s runtime is small and layered: lib/application.js defines the Application class extending Node’s EventEmitter, holding an ordered middleware array that gets composed into a single async function via koa-compose at callback() time. Each incoming request calls createContext(), which builds a fresh Context by prototypally cloning shared context, request, and response objects (lib/context.js, lib/request.js, lib/response.js) and cross-wiring references between them (context.request, request.response, etc.). The Context object uses the delegates library to forward dozens of methods and accessors to the underlying Request/Response objects, so consumers can call ctx.status or ctx.type without reaching into nested objects. Response finalization is centralized in a single respond() function that inspects ctx.body’s type (null, string, buffer, stream, Blob, ReadableStream, or JSON-serializable object) and writes the appropriate response, which keeps body-handling logic in one auditable place rather than scattered across middleware.

Tech Stack

Koa targets Node.js 18+ and depends on a small set of well-established HTTP utility packages: http-errors and http-assert for structured HTTP error creation and assertions, statuses for status code/message lookups, cookies for signed cookie handling, koa-compose for middleware composition, delegates for property/method forwarding, accepts, content-type, type-is, fresh, and vary for content negotiation and caching headers, and on-finished for detecting request completion. The package ships both CommonJS (lib/application.js) and an ESM wrapper (dist/koa.mjs, generated via gen-esm-wrapper) through conditional exports in package.json, so it works natively in both module systems.

Code Quality

The project has an extensive test suite (dozens of test files under __tests__/, covering application, context, request, and response in isolation) using Node’s built-in node:test runner and supertest for HTTP-level assertions, with coverage measured via c8 and uploaded to Codecov on every CI run. Linting is enforced with standard (zero-config ESLint preset) across three Node.js versions in CI (22.x, 24.x, 26.x), and the codebase favors explicit error propagation — errors are converted to typed HTTP errors and surfaced through both ctx.onerror and an app-level error event rather than being silently swallowed.

What Makes It Unique

Koa’s defining choice is what it deliberately omits: no router, no body parser, no templating, no bundled middleware of any kind — only the primitives needed to compose one. Combined with cascading async middleware (each layer can act both before and after everything downstream of it completes) and an optional AsyncLocalStorage-backed context accessor for code outside the request/response chain, Koa trades an all-in-one feature set for a small, comprehensible surface area that composes cleanly with a wide, independently-maintained middleware ecosystem.