koa-logger

koa-logger is a small middleware for the Koa web framework that prints a development-style request log line for every incoming HTTP request and its matching response. Each request produces an inbound line (method and URL) and an outbound line (method, URL, status code color-coded by response class, elapsed time, and formatted response size), making it easy to watch traffic flow through an app during local development.

Under the hood it hooks into Koa’s middleware chain, wrapping next() so it can time the full request lifecycle and using on-finished to log once the response actually completes or the connection closes — including for streamed responses, where it transparently counts bytes as they pass through via a passthrough counter when no Content-Length header is already set. Output can be redirected through a custom transporter function instead of the default console.log, letting it feed into a different sink while keeping the same formatted string and structured argument array.

What You Get

• One-line setup — app.use(logger()) at the top of the middleware stack logs every request that flows through the app
• Colorized status output — response lines are colored by status class (2xx green, 3xx cyan, 4xx yellow, 5xx red) for quick visual scanning
• Accurate timing and size — response time is humanized (ms or s) and response size is formatted with byte units, computed even for streamed bodies via a passthrough byte counter
• Pluggable output — a custom transporter function can redirect the formatted log string and its raw arguments to any destination instead of stdout
• Graceful handling of thrown errors and closed connections — logs a distinct line for downstream errors and for connections closed before the response finished

Common Use Cases

• Local development request tracing — see every request and its outcome scroll by in the terminal while building a Koa API
• Quick debugging of slow or failing endpoints — response time and status color make outliers easy to spot without extra tooling
• Piping formatted request logs into a custom logger or log aggregator via the transporter option
• Verifying middleware ordering and request flow when composing several Koa middlewares together

Under The Hood

Architecture koa-logger is a single-file CommonJS module (index.js) exporting a factory function that returns Koa middleware. The factory closes over an internal print function that either calls a user-supplied transporter or falls back to console.log. The returned middleware logs an inbound line immediately, then calls next() inside a try/catch so downstream errors are logged and rethrown rather than swallowed. After next() resolves, it registers an on-finished callback against the raw response so the outbound log line fires exactly once, whether the response completes normally or the connection closes early; when no Content-Length is set and the body is a readable stream, it pipes the body through a passthrough-counter to measure bytes without buffering the stream itself. It’s a flat, function-composition design with no internal layering — appropriate for its narrow scope.

Tech Stack Plain CommonJS JavaScript with no build step or TypeScript. Runtime dependencies are all small, focused utilities: chalk for ANSI coloring, bytes for human-readable size formatting, humanize-number for readable timing output, on-finished for response-completion detection, and passthrough-counter for streaming byte counts. Development tooling uses xo (an opinionated ESLint preset) with Prettier for formatting, c8 for coverage, and sinon/supertest plus a real koa instance for integration-style tests. The package requires Node >= 18 and ships no dist build — index.js is published as-is.

Code Quality The test suite (test/index.test.js) is large relative to the implementation — over 500 lines covering standard requests, custom transporters, streamed and compressed responses, closed connections, and thrown downstream errors, run against real koa/koa-route/koa-compress instances via supertest rather than mocks alone. CI runs the lint and test-with-coverage scripts across Node 18, 20, and 22. There’s no static type system (plain JS, no TypeScript or JSDoc types), but naming is consistent and the error-handling path explicitly logs and rethrows rather than swallowing failures.

API Design The public surface is a single default export: call it with no arguments, a transporter function, or an options object with a transporter key, then .use() the result. There is no configuration to learn beyond that one option, and the README documents the exact shape of the transporter’s (str, args) callback and the args array format. Getting a working setup requires exactly one line of code, and the escape hatch for redirecting output is the only extension point exposed.