Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
expressWinston
✓ import * as expressWinston from 'express-winston';
✗ import 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
✓ import { logger, errorLogger } from 'express-winston';
✗ import expressWinston from 'express-winston'; // Then expressWinston.logger
For clarity and direct access, `logger` and `errorLogger` can be directly imported as named exports in ESM environments.
expressWinston
✓ const expressWinston = require('express-winston');
✗ import expressWinston from 'express-winston'; // In CommonJS contexts
For CommonJS environments, `require` is the standard and correct method to import the module, which will then expose `expressWinston.logger` and `expressWinston.errorLogger`.
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.');
});
Debug
Known issues
breakingThe `metaField` configuration property functionality changed significantly in `v4.0.0`. Existing configurations using `metaField` may behave differently or require updates.fixReview 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.
affects: >=4.0.0
breakingUpcoming `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.fixMonitor 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.
affects: >=5.0.0 (upcoming)
gotchaThe 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.fixBe 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.
affects: >=4.x
gotchaEnsure `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.fixVerify your `package.json` includes `"winston": "^3.0.0"` (or a compatible 3.x range) in your dependencies, then run `npm install` or `yarn install`.
affects: >=3.0.0
gotchaFor `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.fixEnsure your middleware order follows the pattern: `app.use(expressWinston.logger(...)); app.use(router); app.use(expressWinston.errorLogger(...)); app.use((err, req, res, next) => { ... });`. affects: >=1.0.0
Errors
Common errors & fixes
TypeError: expressWinston.logger is not a function
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.
fixFor 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'
The `winston` library, a required peer dependency for `express-winston`, is not installed or cannot be found by Node.js.
fixInstall `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")'
Incorrect TypeScript import statement, often trying to use a default import for a module that exports named members or a namespace object.
fixUse 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. Audit
Dependencies
winstonrequiredCore logging library; express-winston is a middleware for winston.