Koa Morgan HTTP Logger Middleware

1.0.1 verified Thu Apr 23 auth: no javascript maintenance

koa-morgan is an HTTP request logger middleware for Koa, acting as a wrapper for the popular `morgan` package. It enables developers to log incoming requests and responses in various formats, supporting custom output streams for integration with logging infrastructure like file systems or external services. The latest stable version, 1.0.1, was published over 10 years ago, indicating a lack of active development or a very stable, feature-complete state. It specifically targets Koa v2.x applications, while older 0.x versions supported Koa v1. Its primary differentiator is providing the robust logging capabilities of `morgan` within the Koa middleware pattern. The package is not actively released and new versions are highly unlikely.

Common errors

error TypeError: app.use is not a function ↓

cause This error often occurs when `koa-morgan` is used with a Koa v1 application but `koa-morgan` v1.x is installed, or vice-versa, due to differing API signatures.

fix

Ensure you are using the correct koa-morgan version for your Koa application (v1.x for Koa v2, v0.x for Koa v1). For koa-morgan v0.x, the API is app.use(morgan.middleware(format, options)).

error ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of index.js to a dynamic import() ↓

cause Trying to import `koa-morgan` using CommonJS `require()` syntax when the parent module is an ES module (e.g., in a file with `.mjs` extension or when `"type": "module"` is set in `package.json`).

fix

While koa-morgan is a CommonJS module, this specific error indicates the *importer* is ESM. The most straightforward fix is to ensure the file importing koa-morgan is also CommonJS. If not possible, you might need to dynamically import it using import('koa-morgan').then(module => module.default). However, koa-morgan might not work seamlessly in a pure ESM context due to its age.

error TypeError: Cannot read property 'createWriteStream' of undefined ↓

cause This error typically indicates that the `fs` module was not correctly imported or is unavailable, specifically when configuring a file stream for `koa-morgan`.

fix

Ensure that the fs module is properly imported at the top of your file using const fs = require('fs') and that accessLogStream is correctly initialized before being passed to koa-morgan options. Verify file paths for write stream creation.

Warnings

breaking koa-morgan version 1.x is designed for Koa v2.x. Older applications running Koa v1.x must use koa-morgan 0.x, which has a different middleware registration API (`morgan.middleware(format, options)`). Compatibility between major versions of Koa and koa-morgan is not maintained. ↓

fix For Koa v1 projects, explicitly install and pin `koa-morgan` to a `0.x.x` version. For Koa v2 projects, use `1.x.x` versions. Koa v3.x is not officially supported by `koa-morgan`.

gotcha The `koa-morgan` package is no longer actively maintained, with its last release (1.0.1) over 10 years ago. While functional for Koa v2, it may not receive updates for new Node.js versions, later Koa versions (e.g., Koa v3.x, which requires Node.js v18+ and dropped generator support), or critical security patches. ↓

fix For new projects or those requiring active support and modern features, consider alternative actively maintained Koa logging middleware or integrate the `morgan` package directly with a custom Koa middleware for greater control and future compatibility.

gotcha koa-morgan is a CommonJS module. Attempting to import it using ES module syntax (e.g., `import morgan from 'koa-morgan'`) will likely result in an `ERR_REQUIRE_ESM` or similar error in projects configured for ESM, as it predates Node.js's widespread ESM adoption. ↓

fix Always use `const morgan = require('koa-morgan')` for importing this package. If your project is strictly ESM, you might need to use a dynamic import (`await import('koa-morgan')`) or consider a different logging library with native ESM support.

Install

npm install koa-morgan

yarn add koa-morgan

pnpm add koa-morgan

Imports

morgan
```
const morgan = require('koa-morgan')
```
This is the primary CommonJS import for the middleware function, which is the only exposed export of koa-morgan.
morgan
wrong
```
import { morgan } from 'koa-morgan'
```
correct
```
import morgan from 'koa-morgan'
```
koa-morgan does not officially support ESM imports. While 'import morgan from 'koa-morgan'' might work in some transpiled environments, the package was published before widespread Node.js ESM adoption. Using named imports like 'import { morgan } from 'koa-morgan'' will fail as there are no named exports. The safest approach is CommonJS `require`.

Quickstart

Demonstrates basic setup of koa-morgan to log HTTP requests in 'combined' format to a file stream in a Koa v2 application.

const fs = require('fs')
const Koa = require('koa')
const morgan = require('koa-morgan')

// Create a write stream (in append mode) for access logs
const accessLogStream = fs.createWriteStream(__dirname + '/access.log',
                                             { flags: 'a' })
const app = new Koa()

// Setup the logger middleware
app.use(morgan('combined', { stream: accessLogStream }))

// Example route
app.use((ctx) => {
  ctx.body = 'hello, world!'
})

// Start the server
app.listen(2333, () => {
  console.log('Server listening on http://localhost:2333')
})