{"id":17748,"library":"koa-morgan","title":"Koa Morgan HTTP Logger Middleware","description":"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.","status":"maintenance","version":"1.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/koa-modules/morgan","tags":["javascript","logger","morgan"],"install":[{"cmd":"npm install koa-morgan","lang":"bash","label":"npm"},{"cmd":"yarn add koa-morgan","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-morgan","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the core HTTP logging functionality that koa-morgan wraps.","package":"morgan","optional":false},{"reason":"Implicit peer dependency for Koa middleware integration. Requires Koa v2.x for koa-morgan v1.x.","package":"koa","optional":false}],"imports":[{"note":"This is the primary CommonJS import for the middleware function, which is the only exposed export of koa-morgan.","symbol":"morgan","correct":"const morgan = require('koa-morgan')"},{"note":"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`.","wrong":"import { morgan } from 'koa-morgan'","symbol":"morgan","correct":"import morgan from 'koa-morgan'"}],"quickstart":{"code":"const fs = require('fs')\nconst Koa = require('koa')\nconst morgan = require('koa-morgan')\n\n// Create a write stream (in append mode) for access logs\nconst accessLogStream = fs.createWriteStream(__dirname + '/access.log',\n                                             { flags: 'a' })\nconst app = new Koa()\n\n// Setup the logger middleware\napp.use(morgan('combined', { stream: accessLogStream }))\n\n// Example route\napp.use((ctx) => {\n  ctx.body = 'hello, world!'\n})\n\n// Start the server\napp.listen(2333, () => {\n  console.log('Server listening on http://localhost:2333')\n})","lang":"javascript","description":"Demonstrates basic setup of koa-morgan to log HTTP requests in 'combined' format to a file stream in a Koa v2 application."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"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))`.","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.","error":"TypeError: app.use is not a function"},{"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.","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`).","error":"ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of index.js to a dynamic import()"},{"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.","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`.","error":"TypeError: Cannot read property 'createWriteStream' of undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}