Koa Logger Middleware

4.0.0 · active · verified Wed Apr 22

Koa-logger is a development-style logging middleware for Koa.js applications, providing colorful, concise HTTP request and response logging to the console. The current stable version, 4.0.0, was released after a period of lower activity, signaling a revival of the project and bringing support for Koa v3 and Node.js versions 18 and higher. It outputs request method, URL, response status, duration, and content length, often formatted with ANSI colors for readability. A key differentiator is its customizable `transporter` option, which allows developers to redirect log output to alternative pipes or logging systems, rather than just `process.stdout`. While primarily a CommonJS package, its updates ensure compatibility with modern Node.js environments and Koa framework versions.

Common errors

```
TypeError: app.use is not a function
```
cause Koa is not correctly initialized or imported, or 'app' is not a Koa application instance.

fix Ensure 'koa' is installed (`npm install koa`) and you are creating a Koa application instance with `const Koa = require('koa'); const app = new Koa();`.
```
TypeError: koa_logger_1.default is not a function
```
cause Attempting to use an ESM default import syntax (`import logger from 'koa-logger';`) for a package that is primarily CommonJS in an environment where direct CJS-ESM interop is not configured or fails.

fix Use the CommonJS require syntax: `const logger = require('koa-logger');`. If you must use ESM, ensure your build setup correctly handles CJS module imports.
```
ReferenceError: logger is not defined
```
cause The `koa-logger` middleware was not imported or assigned to the `logger` variable before being used.

fix Add `const logger = require('koa-logger');` at the top of your file to import the middleware.

Warnings

breaking Koa-logger v4.0.0 dropped support for Node.js versions older than 10. Users on Node.js < 18 (the recommended version for v4) should upgrade their Node.js runtime or use an older version of koa-logger.
Fix: Upgrade Node.js to version 18 or higher. If unable to upgrade Node.js, consider using koa-logger v3.x or earlier.
breaking Koa-logger v4.0.0 explicitly adds support for Koa v3. While it might work with Koa v2, compatibility issues may arise due to potential API changes in Koa itself. It's recommended to align Koa and koa-logger versions.
Fix: Ensure your Koa application is running Koa v3.x when using koa-logger v4.x. If using Koa v2.x, consider pinning koa-logger to an earlier major version (e.g., v3.x).
gotcha For comprehensive logging, koa-logger should be applied as early as possible in the middleware stack (e.g., `app.use(logger())` near the top). Placing it after other middleware might result in those preceding middleware's operations not being fully captured in the log.
Fix: Always place `app.use(logger())` as one of the first middleware in your Koa application setup to ensure it 'wraps' all subsequent middleware and accurately logs all request/response cycles.

Install

npm install koa-logger npm
yarn add koa-logger yarn
pnpm add koa-logger pnpm

Imports

logger
wrong:
```
import logger from 'koa-logger'
```
correct:
```
const logger = require('koa-logger')
```
Koa-logger v4.x is primarily a CommonJS package. While Node.js 18+ supports ESM, direct 'import' statements for this package may not work as expected without specific transpilation or Node.js configurations. Use 'require' for direct CommonJS usage.
logger
wrong:
```
import { logger } from 'koa-logger';
```
correct:
```
import logger from 'koa-logger';
```
While primarily CommonJS, if you are using an environment that transpiles CommonJS to ESM or are using Node.js's CJS-ESM interop, `import logger from 'koa-logger'` would be the correct pattern for its default export. `import { logger } from 'koa-logger'` is incorrect as it's not a named export.

Quickstart

This quickstart demonstrates how to initialize a basic Koa application and integrate `koa-logger` as the primary logging middleware, showing its effect on console output for various HTTP requests.

const Koa = require('koa');
const logger = require('koa-logger');

const app = new Koa();

// Use koa-logger middleware as early as possible to wrap all subsequent middleware
app.use(logger());

// Example middleware to handle requests
app.use(async (ctx, next) => {
  if (ctx.path === '/') {
    ctx.body = 'Hello, Koa-logger!';
  } else if (ctx.path === '/users') {
    ctx.body = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
  } else {
    ctx.status = 404;
    ctx.body = 'Not Found';
  }
  await next(); // Pass control to subsequent middleware
});

const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Koa server running on http://localhost:${port}`);
});

// To run this:
// 1. npm install koa koa-logger
// 2. node your-file-name.js
// 3. Open http://localhost:3000 or http://localhost:3000/users in your browser.

view raw JSON →