Koa Pino Logger

5.0.0 · active · verified Wed Apr 22

koa-pino-logger is a high-performance Koa middleware for integrating the Pino JSON logger into web applications. Currently at version 5.0.0, it offers rapid, structured logging with minimal overhead, differentiating itself from alternatives like koa-bunyan-logger, koa-logger, and koa-morgan through its speed, native JSON output, support for arbitrary data, and avoidance of `eval` for performance. Its release cadence is sporadic, typically aligning with major updates to the underlying `pino` logger or the `Koa` framework. It's particularly favored for production environments where log processing efficiency and structured output are critical for observability platforms.

Common errors

```
TypeError: ctx.log is undefined
```
cause The `koa-pino-logger` middleware was not applied to the Koa application, or `ctx.log` is being accessed before the middleware has executed for a given request.

fix Ensure `app.use(logger());` is called early in your Koa application's middleware chain, before any middleware that attempts to use `ctx.log`.
```
Error: Cannot find module 'koa'
```
cause The `koa` package, a peer dependency, is not installed in the project.

fix Install Koa: `npm install koa` or `yarn add koa`.
```
Error: Cannot find module 'pino'
```
cause The `pino` package, a peer dependency, is not installed, or `koa-pino-logger`'s internal dependency resolution for `pino` failed.

fix Install Pino: `npm install pino` or `yarn add pino`. Ensure it's available for `koa-pino-logger` to use.
```
TypeError: app.use is not a function
```
cause Attempting to use `app.use` on an object that is not a Koa application instance, or `Koa` was imported incorrectly.

fix Verify that `app` is an instance of `Koa` (e.g., `const app = new Koa();`) and that `koa` is correctly imported (e.g., `import Koa from 'koa';` or `const Koa = require('koa');`).

Warnings

breaking Version 5.0.0 drops support for Node.js 12 and adds support for Node.js 18. Ensure your environment meets this new requirement.
Fix: Upgrade your Node.js runtime to version 18 or higher.
breaking Version 4.0.0 updated to use `pino@7`. This may introduce breaking changes or deprecations inherited from Pino itself, particularly concerning how transports work with `pino.transport` and handling of `pino.final()`.
Fix: Review Pino v7 release notes and adapt any custom Pino configurations, especially around transports and exit handling.
gotcha koa-pino-logger is designed for Koa v2 and above. Using it with Koa v1 (which uses generator functions) will lead to compatibility issues.
Fix: Ensure your Koa application is running on Koa v2 or later. If on Koa v1, refer to the `v1 readme` on the package's GitHub or migrate your Koa application.
gotcha When logging thrown errors, Koa's default error handling prints to `console.error`. To prevent duplicate output with `koa-pino-logger`, set `app.silent = true` on your Koa application instance.
Fix: Add `app.silent = true;` after `const app = new Koa();` to suppress Koa's default error logging.

Install

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

Imports

koaPinoLogger
wrong:
```
const koaPinoLogger = require('koa-pino-logger').default
```
correct:
```
import koaPinoLogger from 'koa-pino-logger'
```
While the example uses `require()`, modern Koa applications often use ESM. The default export is the middleware function.
Koa
wrong:
```
const Koa = require('koa')
```
correct:
```
import Koa from 'koa'
```
CommonJS `require('koa')` is still prevalent in older projects, but `import Koa from 'koa'` is standard for ESM.
Middleware
wrong:
```
import { KoaMiddleware } from 'koa'
```
correct:
```
import { Middleware } from 'koa'
```
Types for Koa's middleware are generally imported from 'koa' or '@types/koa'. koa-pino-logger extends `ctx.log`.

Quickstart

This example demonstrates how to set up `koa-pino-logger` in a basic Koa application to automatically log requests and allows accessing the logger instance on `ctx.log` for custom logging within middleware.

import Koa from 'koa';
import pinoLogger from 'koa-pino-logger';

const app = new Koa();

// Initialize the logger middleware
const loggerMiddleware = pinoLogger();
app.use(loggerMiddleware);

// Access the logger via ctx.log within downstream middleware
app.use((ctx) => {
  ctx.log.info({ user: 'example-user' }, 'Request processed for user');
  ctx.body = 'Hello world with logging';
});

const PORT = process.env.PORT ?? 3000;
app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
  console.log('Test with: curl http://localhost:3000 | pino');
});

view raw JSON →