Express Winston Middleware

Common errors

• TypeError: expressWinston.logger is not a function

  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.
  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');`.

• Error: Cannot find module 'winston'

  cause The `winston` library, a required peer dependency for `express-winston`, is not installed or cannot be found by Node.js.
  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.

• TypeScript compilation error: Property 'logger' does not exist on type 'typeof import("/path/to/node_modules/express-winston/index.d.ts")'

  cause Incorrect TypeScript import statement, often trying to use a default import for a module that exports named members or a namespace object.
  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.

Warnings

• breaking The `metaField` configuration property functionality changed significantly in `v4.0.0`. Existing configurations using `metaField` may behave differently or require updates.
  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.
• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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`.
• gotcha 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.
  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) => { ... });`.

Install

• npm install express-winston npm
• yarn add express-winston yarn
• pnpm add express-winston pnpm

Imports

• expressWinston
  wrong:

  import expressWinston from 'express-winston';

  correct:

  import * as expressWinston from 'express-winston';

  The library exports an object containing `logger` and `errorLogger` methods. Use a namespace import for ESM or `require` for CJS to access these methods.
• logger, errorLogger
  wrong:

  import expressWinston from 'express-winston'; // Then expressWinston.logger

  correct:

  import { logger, errorLogger } from 'express-winston';

  For clarity and direct access, `logger` and `errorLogger` can be directly imported as named exports in ESM environments.
• expressWinston
  wrong:

  import expressWinston from 'express-winston'; // In CommonJS contexts

  correct:

  const expressWinston = require('express-winston');

  For CommonJS environments, `require` is the standard and correct method to import the module, which will then expose `expressWinston.logger` and `expressWinston.errorLogger`.

Quickstart

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.

import express from 'express';
import winston from 'winston';
import * as expressWinston from 'express-winston';

const app = express();

const logger = winston.createLogger({
  transports: [
    new winston.transports.Console({
      format: winston.format.combine(
        winston.format.colorize(),
        winston.format.simple()
      )
    })
  ]
});

// Request Logger: Logs all incoming HTTP requests
app.use(expressWinston.logger({
  winstonInstance: logger,
  meta: true, // Log request metadata (ip, url, method, body, etc.)
  msg: "HTTP {{req.method}} {{req.url}} {{res.statusCode}} {{res.responseTime}}ms",
  colorize: true,
  statusLevels: true // Use different log levels based on HTTP status codes
}));

app.get('/', (req, res) => {
  res.status(200).send('Hello, World! This is a logged request.');
});

app.get('/error-route', (req, res, next) => {
  // Simulate an error
  next(new Error('Oops! Something went wrong on this route.'));
});

// Error Logger: Must be placed after the router but before any other error handling middleware
app.use(expressWinston.errorLogger({
  winstonInstance: logger,
  meta: true, // Log error metadata (stack trace, request info)
  msg: "HTTP Error encountered: {{err.message}}",
  colorize: true
}));

// Custom error handler (after express-winston.errorLogger)
app.use((err, req, res, next) => {
  console.error(`Caught by custom error handler: ${err.message}`);
  res.status(500).send('An unexpected error occurred!');
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
  console.log('Try visiting / and /error-route to see logs.');
});