{"id":10432,"library":"winston","title":"Winston.js Logging Library","description":"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.","status":"active","version":"3.19.0","language":"javascript","source_language":"en","source_url":"https://github.com/winstonjs/winston","tags":["javascript","winston","logger","logging","logs","sysadmin","bunyan","pino","loglevel","typescript"],"install":[{"cmd":"npm install winston","lang":"bash","label":"npm"},{"cmd":"yarn add winston","lang":"bash","label":"yarn"},{"cmd":"pnpm add winston","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For ESM projects, use named imports. `createLogger` is the modern way to instantiate a logger since v3. The `Logger` type is for TypeScript annotations.","wrong":"const winston = require('winston'); const logger = new winston.Logger();","symbol":"createLogger","correct":"import { createLogger, format, transports, Logger } from 'winston';"},{"note":"All standard formats are available as properties on the `format` object imported from the main 'winston' package.","wrong":"import { json } from 'winston/format';","symbol":"format","correct":"import { format } from 'winston'; logger.format(format.json());"},{"note":"Standard transports (Console, File) are accessed via the `transports` object from the main 'winston' package, not internal paths. Custom transports are typically separate packages.","wrong":"import { ConsoleTransport } from 'winston/transports/console';","symbol":"transports","correct":"import { transports } from 'winston'; new transports.Console();"},{"note":"The standard CommonJS import pattern, still fully supported by Winston.","symbol":"CommonJS require","correct":"const winston = require('winston'); const logger = winston.createLogger();"}],"quickstart":{"code":"import { createLogger, format, transports, Logger } from 'winston';\n\n// Create a logger instance\nconst logger: Logger = createLogger({\n  level: 'info', // Set the default logging level\n  format: format.json(), // Use JSON format for structured logs\n  defaultMeta: { service: 'user-service' }, // Default metadata for all logs\n  transports: [\n    // Transport for error-level logs and higher to a dedicated file\n    new transports.File({ filename: 'error.log', level: 'error' }),\n    // Transport for info-level logs and higher to a combined file\n    new transports.File({ filename: 'combined.log' })\n  ]\n});\n\n// Add a console transport if not in production environment\nif (process.env.NODE_ENV !== 'production') {\n  logger.add(new transports.Console({\n    format: format.combine(\n      format.colorize(), // Add color to the console output\n      format.simple()    // Use a simple format for console readability\n    )\n  }));\n}\n\n// Example log messages\nlogger.info('Application started successfully.', { transactionId: 'txn-123' });\nlogger.warn('A potential configuration issue was detected.', { configPath: '/app/config.js' });\nlogger.error('Failed to connect to the database.', new Error('Connection refused by DB server.'));\nlogger.debug('This debug message will not appear in production logs.');\n\n// Simulate an async operation and log its completion\nasync function performTask() {\n  logger.info('Starting critical task...');\n  await new Promise(resolve => setTimeout(resolve, 1000)); // Simulate work\n  logger.info('Critical task completed.', { durationMs: 1000 });\n}\nperformTask();","lang":"typescript","description":"Initializes a Winston logger with file and console transports, demonstrating different log levels, metadata, and conditional configuration for development vs. production environments."},"warnings":[{"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.","message":"Winston 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.","severity":"breaking","affected_versions":">=3.0.0"},{"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()`.","message":"Using 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"In `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.","severity":"breaking","affected_versions":">=3.15.0"},{"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, ... }`.","message":"Winston'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.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"search_vec":"'3.19.0':29 'address':36 'allow':72 'also':104 'applic':21 'architectur':50 'bug':37 'bunyan':134 'compon':58 'configur':75 'consol':102 'control':114 'current':25 'custom':106 'databas':92 'decoupl':52 'depend':39 'design':15 'devic':62 'differ':79 'differenti':47 'distinguish':122 'dynam':110 'enhanc':44 'environ':23 'error':88 'extens':10 'featur':43 'file':100 'fix':38 'flexibl':8 'format':66,83,111 'generat':119 'granular':113 'handl':17 'high':7 'javascript':128 'key':46 'level':81,108 'librari':3,12 'like':59 'local':99 'log':2,11,18,54,64,68,80,96,107,117,126,131,132 'logger':130 'loglevel':136 'messag':69 'minor':34,42 'modular':57 'multipl':76 'node.js':14 'output':94 'patch':32 'pino':135 'present':70 'process':55 'provid':112 'regular':31 'releas':35 'remot':91 'rule':84 'send':87 'simpler':125 'stabl':26 'storag':61 'store':121 'support':105 'sysadmin':133 'transport':60,77 'typescript':137 'updat':40 'user':73 'util':127 'various':20 'version':27 'winston':4,103,129 'winston.js':1","created_at":"2026-04-18T08:58:46.103423+00:00","updated_at":"2026-04-19T06:06:24.210359+00:00","problems":[{"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.","cause":"Attempting to use `winston.createLogger()` with an older version of Winston (pre-3.x) where the API was different, or importing incorrectly in CJS.","error":"TypeError: winston.createLogger is not a function"},{"fix":"Add at least one transport to your logger configuration, for example: `transports: [new winston.transports.Console()]` when calling `createLogger`.","cause":"The `winston.createLogger()` call or the default logger instance was initialized without any active transports, meaning logs have nowhere to go.","error":"No transports were configured to handle message."},{"fix":"Always import transports and formats from the main 'winston' package: `import { transports, format } from 'winston'; new transports.Console();`","cause":"You are attempting to import internal modules of Winston directly, which are not part of the public API and may change without notice.","error":"Error: Cannot find module 'winston/lib/winston/transports'"},{"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.","cause":"TypeScript is indicating that your `createLogger` options object does not conform to the `LoggerOptions` interface, or your `@types/winston` package is outdated/missing.","error":"Property 'level' does not exist on type 'LoggerOptions'. (TypeScript error)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.3.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/winstonjs/winston","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/winston","openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}