winston — Versatile Logging Library for Node.js

Introduction

winston is a multi-transport async logging library for Node.js designed to be simple and extensible. It decouples log formatting from log storage, letting you send structured logs to the console, files, databases, or cloud services simultaneously.

What winston Does

• Creates loggers with configurable severity levels (error, warn, info, debug, etc.)
• Routes log entries to one or more transports (console, file, HTTP, stream)
• Formats log output as JSON, plain text, colorized, or custom formats
• Supports child loggers that inherit parent configuration with added metadata
• Handles uncaught exceptions and unhandled promise rejections

Architecture Overview

A winston logger is composed of three layers: formats (transform pipeline), transports (output destinations), and levels (severity filtering). When logger.info() is called, the message passes through the format pipeline, which can add timestamps, colorize output, or restructure data. The formatted entry is then written to each transport whose level threshold is met. Transports are asynchronous and can buffer writes.

Self-Hosting & Configuration

• Install via npm install winston and optionally add transport packages
• Create a logger with winston.createLogger() specifying level, format, and transports
• Use winston.format.combine() to chain multiple format transforms (timestamp, json, colorize)
• Add file transports with new winston.transports.File({ filename: 'app.log' })
• Set handleExceptions: true and handleRejections: true to capture uncaught errors

Key Features

• Multiple simultaneous transports with independent log level filtering
• Rich format pipeline: timestamp, printf, colorize, metadata, errors, splat
• Custom log levels beyond the default npm/syslog conventions
• Exception and rejection handling with dedicated transports
• Community transports for MongoDB, Redis, Elasticsearch, Syslog, and more

Comparison with Similar Tools

• Pino — JSON-first logger focused on raw speed; winston offers more format flexibility and transport options
• Bunyan — structured JSON logging with CLI viewer; winston has a larger ecosystem of community transports
• Morgan — HTTP request logger middleware; winston is a general-purpose logger for all application events
• Loguru (Python) — Python logging with batteries included; winston fills the same role in Node.js
• log4js — configurable logging with appenders; winston's format pipeline and transport system are more composable

FAQ

Q: How do I log to both console and file simultaneously? A: Pass an array of transports to createLogger: one Console and one File transport, each with their own format and level.

Q: Can I use winston with TypeScript? A: Yes. winston ships with TypeScript type definitions. Import and use it the same way as in JavaScript.

Q: How do I add request context (like request ID) to every log? A: Use child loggers (logger.child({ requestId })) or a custom format that reads from async local storage.

Q: Does winston support log rotation? A: The core File transport does not rotate. Use winston-daily-rotate-file for size-based or date-based log rotation.

Sources

• https://github.com/winstonjs/winston
• https://github.com/winstonjs/winston#readme