{"id":17097,"library":"express-winston","title":"Express Winston Middleware","description":"express-winston is an Express.js middleware package that integrates the popular Winston logging library into web applications, enabling structured request and error logging. The current stable version is 4.2.0. The project maintains a somewhat active release cadence, frequently addressing dependency updates, security fixes, and minor feature enhancements within the 4.x series. Its key differentiators include extensive configuration options for filtering request/response metadata (e.g., using whitelists and blacklists, though these terms are slated for removal in v5.x), dynamic log levels, and the ability to leverage any of Winston's powerful transports and formatting capabilities directly within the Express middleware stack for both HTTP request logging and centralized error handling.","status":"active","version":"4.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/bithavoc/express-winston","tags":["javascript","winston","logging","express","log","error","handler","middleware","colors","typescript"],"install":[{"cmd":"npm install express-winston","lang":"bash","label":"npm"},{"cmd":"yarn add express-winston","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-winston","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core logging library; express-winston is a middleware for winston.","package":"winston","optional":false}],"imports":[{"note":"The library exports an object containing `logger` and `errorLogger` methods. Use a namespace import for ESM or `require` for CJS to access these methods.","wrong":"import expressWinston from 'express-winston';","symbol":"expressWinston","correct":"import * as expressWinston from 'express-winston';"},{"note":"For clarity and direct access, `logger` and `errorLogger` can be directly imported as named exports in ESM environments.","wrong":"import expressWinston from 'express-winston'; // Then expressWinston.logger","symbol":"logger, errorLogger","correct":"import { logger, errorLogger } from 'express-winston';"},{"note":"For CommonJS environments, `require` is the standard and correct method to import the module, which will then expose `expressWinston.logger` and `expressWinston.errorLogger`.","wrong":"import expressWinston from 'express-winston'; // In CommonJS contexts","symbol":"expressWinston","correct":"const expressWinston = require('express-winston');"}],"quickstart":{"code":"import express from 'express';\nimport winston from 'winston';\nimport * as expressWinston from 'express-winston';\n\nconst app = express();\n\nconst logger = winston.createLogger({\n  transports: [\n    new winston.transports.Console({\n      format: winston.format.combine(\n        winston.format.colorize(),\n        winston.format.simple()\n      )\n    })\n  ]\n});\n\n// Request Logger: Logs all incoming HTTP requests\napp.use(expressWinston.logger({\n  winstonInstance: logger,\n  meta: true, // Log request metadata (ip, url, method, body, etc.)\n  msg: \"HTTP {{req.method}} {{req.url}} {{res.statusCode}} {{res.responseTime}}ms\",\n  colorize: true,\n  statusLevels: true // Use different log levels based on HTTP status codes\n}));\n\napp.get('/', (req, res) => {\n  res.status(200).send('Hello, World! This is a logged request.');\n});\n\napp.get('/error-route', (req, res, next) => {\n  // Simulate an error\n  next(new Error('Oops! Something went wrong on this route.'));\n});\n\n// Error Logger: Must be placed after the router but before any other error handling middleware\napp.use(expressWinston.errorLogger({\n  winstonInstance: logger,\n  meta: true, // Log error metadata (stack trace, request info)\n  msg: \"HTTP Error encountered: {{err.message}}\",\n  colorize: true\n}));\n\n// Custom error handler (after express-winston.errorLogger)\napp.use((err, req, res, next) => {\n  console.error(`Caught by custom error handler: ${err.message}`);\n  res.status(500).send('An unexpected error occurred!');\n});\n\nconst PORT = process.env.PORT || 3000;\napp.listen(PORT, () => {\n  console.log(`Server listening on port ${PORT}`);\n  console.log('Try visiting / and /error-route to see logs.');\n});","lang":"typescript","description":"This quickstart demonstrates setting up both request and error logging middleware for an Express application. It configures a Winston console transport, logs request and error metadata, and uses dynamic status levels for request logging."},"warnings":[{"fix":"Review the official documentation for `v4.0.0` regarding `metaField` to understand its new behavior. Consider using `requestField` and `responseField` for more granular control over logged request and response properties.","message":"The `metaField` configuration property functionality changed significantly in `v4.0.0`. Existing configurations using `metaField` may behave differently or require updates.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Monitor the project's GitHub issues (specifically [#247]) for updates on alternative naming conventions and prepare to update your application's configuration when `v5.x` is officially released.","message":"Upcoming `v5.x` releases will introduce breaking changes by removing or renaming configuration options and types that use terms like `whitelist` and `blacklist`. This is part of a project initiative to update terminology.","severity":"breaking","affected_versions":">=5.0.0 (upcoming)"},{"fix":"Be aware of the project's maintenance status. If critical to your application, consider contributing to the project or evaluating its long-term viability and community support.","message":"The project has issued a 'CALL FOR MAINTAINERS', indicating that while current `v4.x` updates are ongoing, the long-term maintenance and future development roadmap may become uncertain without new contributors.","severity":"gotcha","affected_versions":">=4.x"},{"fix":"Verify your `package.json` includes `\"winston\": \"^3.0.0\"` (or a compatible 3.x range) in your dependencies, then run `npm install` or `yarn install`.","message":"Ensure `winston` is installed as a peer dependency with a compatible version (`>=3.x <4`). Mismatched or missing `winston` installations can lead to runtime errors, module not found issues, or unexpected logging behavior.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Ensure your middleware order follows the pattern: `app.use(expressWinston.logger(...)); app.use(router); app.use(expressWinston.errorLogger(...)); app.use((err, req, res, next) => { ... });`.","message":"For `express-winston.errorLogger` to function correctly, it must be placed *after* your Express router but *before* any other custom error-handling middleware. Incorrect placement will prevent `express-winston` from catching and logging application errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"For ESM, use `import * as expressWinston from 'express-winston';` or `import { logger, errorLogger } from 'express-winston';`. For CommonJS, ensure `const expressWinston = require('express-winston');`.","cause":"Attempting to access `logger` directly on `expressWinston` after an incorrect ES module default import or `require` statement that doesn't correctly resolve the module's exports.","error":"TypeError: expressWinston.logger is not a function"},{"fix":"Install `winston` explicitly in your project: `npm install winston@^3.0.0` or `yarn add winston@^3.0.0`. Verify that your `package.json` lists a compatible `winston` version.","cause":"The `winston` library, a required peer dependency for `express-winston`, is not installed or cannot be found by Node.js.","error":"Error: Cannot find module 'winston'"},{"fix":"Use a namespace import: `import * as expressWinston from 'express-winston';` or specifically named imports: `import { logger, errorLogger } from 'express-winston';` to correctly leverage the provided type definitions.","cause":"Incorrect TypeScript import statement, often trying to use a default import for a module that exports named members or a namespace object.","error":"TypeScript compilation error: Property 'logger' does not exist on type 'typeof import(\"/path/to/node_modules/express-winston/index.d.ts\")'"}],"ecosystem":"npm","meta_description":null}