Registry / observability / winston

winston

JSON →
library0.3.0jsnpmunverified

Winston is a highly flexible and extensible logging library for Node.js, designed to handle logs for various applications and environments. Its current stable version is 3.19.0, with regular patch and minor releases addressing bug fixes, dependency updates, and minor feature enhancements. A key differentiator is its architecture, which decouples the logging process into modular components like transports (storage devices for logs) and formats (for log message presentation). This allows users to configure multiple transports with different logging levels and formatting rules, such as sending errors to a remote database while outputting all logs to a local file or console. Winston also supports custom logging levels and dynamic formatting, providing granular control over how logs are generated and stored, distinguishing it from simpler logging utilities.

npm install winston
INSTALL
IMPORT
SIG · WINSTON
W
winston
observabilityjavascriptv0.3.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createLogger
import { createLogger, format, transports, Logger } from 'winston';
const winston = require('winston'); const logger = new winston.Logger();
For ESM projects, use named imports. `createLogger` is the modern way to instantiate a logger since v3. The `Logger` type is for TypeScript annotations.
format
import { format } from 'winston'; logger.format(format.json());
import { json } from 'winston/format';
All standard formats are available as properties on the `format` object imported from the main 'winston' package.
transports
import { transports } from 'winston'; new transports.Console();
import { ConsoleTransport } from 'winston/transports/console';
Standard transports (Console, File) are accessed via the `transports` object from the main 'winston' package, not internal paths. Custom transports are typically separate packages.
CommonJS require
const winston = require('winston'); const logger = winston.createLogger();
The standard CommonJS import pattern, still fully supported by Winston.

Initializes a Winston logger with file and console transports, demonstrating different log levels, metadata, and conditional configuration for development vs. production environments.

import { createLogger, format, transports, Logger } from 'winston'; // Create a logger instance const logger: Logger = createLogger({ level: 'info', // Set the default logging level format: format.json(), // Use JSON format for structured logs defaultMeta: { service: 'user-service' }, // Default metadata for all logs transports: [ // Transport for error-level logs and higher to a dedicated file new transports.File({ filename: 'error.log', level: 'error' }), // Transport for info-level logs and higher to a combined file new transports.File({ filename: 'combined.log' }) ] }); // Add a console transport if not in production environment if (process.env.NODE_ENV !== 'production') { logger.add(new transports.Console({ format: format.combine( format.colorize(), // Add color to the console output format.simple() // Use a simple format for console readability ) })); } // Example log messages logger.info('Application started successfully.', { transactionId: 'txn-123' }); logger.warn('A potential configuration issue was detected.', { configPath: '/app/config.js' }); logger.error('Failed to connect to the database.', new Error('Connection refused by DB server.')); logger.debug('This debug message will not appear in production logs.'); // Simulate an async operation and log its completion async function performTask() { logger.info('Starting critical task...'); await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate work logger.info('Critical task completed.', { durationMs: 1000 }); } performTask();
Debug
Known issues
breakingWinston v3 introduced significant breaking changes from v2.x, including a new API for `createLogger`, `format`, and how transports are instantiated. Direct upgrade without consulting the v3 upgrade guide will lead to errors.
fix
Refer to the `UPGRADE-3.0.md` guide in the Winston GitHub repository when migrating from v2.x. Update `require('winston')` to `winston.createLogger(...)` and adjust format/transport instantiations.
affects: >=3.0.0
gotchaUsing the default logger (`require('winston')`) without explicitly adding transports can lead to high memory usage and logs being silently dropped. The default logger starts with no transports configured.
fix
Always add at least one transport (e.g., `winston.add(new winston.transports.Console());`) to the default logger if you choose to use it, or preferably, create a custom logger instance with `winston.createLogger()`.
affects: >=3.0.0
breakingIn `v3.15.0`, the `LogCallback` type was removed from Winston's TypeScript definitions. Code relying on this type for callback-based logging will now show TypeScript errors.
fix
Remove references to `LogCallback` in your TypeScript code. The underlying library did not effectively support these callbacks, and their removal clarifies the API. If async operations are needed, use promises or async/await patterns.
affects: >=3.15.0
gotchaWinston's log levels default to npm's logging levels (error, warn, info, http, verbose, debug, silly). If you expect levels like 'trace' or 'fatal', you'll need to define custom levels.
fix
Configure custom levels using the `levels` option in `createLogger()` and ensure your formats and transports are aware of these custom levels. Example: `levels: { fatal: 0, error: 1, ... }`.
affects: >=3.0.0
Errors
Common errors & fixes
TypeError: winston.createLogger is not a function
Attempting to use `winston.createLogger()` with an older version of Winston (pre-3.x) where the API was different, or importing incorrectly in CJS.
fix
Ensure you have `winston@^3.0.0` installed (`npm install winston@latest`) and are using `import { createLogger } from 'winston'` for ESM, or `const winston = require('winston');` for CJS.
No transports were configured to handle message.
The `winston.createLogger()` call or the default logger instance was initialized without any active transports, meaning logs have nowhere to go.
fix
Add at least one transport to your logger configuration, for example: `transports: [new winston.transports.Console()]` when calling `createLogger`.
Error: Cannot find module 'winston/lib/winston/transports'
You are attempting to import internal modules of Winston directly, which are not part of the public API and may change without notice.
fix
Always import transports and formats from the main 'winston' package: `import { transports, format } from 'winston'; new transports.Console();`
Property 'level' does not exist on type 'LoggerOptions'. (TypeScript error)
TypeScript is indicating that your `createLogger` options object does not conform to the `LoggerOptions` interface, or your `@types/winston` package is outdated/missing.
fix
Ensure `@types/winston` is installed and up-to-date (`npm install --save-dev @types/winston`). Verify that the `level` property is correctly placed within the `createLogger` options object.
Upgrade
Version history
0.3.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
37 hits · last 30 days
node
30
OpenAI (training)
1
Resources
winston — npm install winston · libregistry