nest-winston

nest-winston integrates the winston logging library into NestJS applications as a proper Nest module, so a winston logger instance is registered through Nest’s dependency-injection container instead of being imported as a bare global object. It implements Nest’s LoggerService interface, letting a winston logger fully replace Nest’s built-in console logger (including framework-internal log calls) via app.useLogger().

The module supports both synchronous (forRoot) and async factory-based (forRootAsync) configuration, exposes a standalone WinstonModule.createLogger() for use before the Nest application context exists (e.g. bootstrap-time logging), and ships Nest-flavored winston formatting utilities (nestLike) that mimic the default Nest console output while running through winston’s transport pipeline.

What You Get

• WinstonModule.forRoot() / forRootAsync() to register a configured winston logger as an injectable Nest provider
• WinstonModule.createLogger() for bootstrap-time logging before the Nest app context is created
• A LoggerService-compatible wrapper so app.useLogger() can replace Nest’s console logger app-wide, including internal framework logs
• utilities.format.nestLike() winston formatter reproducing Nest’s familiar colored console output through winston transports
• Full access to winston’s transport ecosystem (files, HTTP, third-party log services) from within a standard Nest provider

Common Use Cases

• Replacing Nest’s built-in console logger app-wide with winston so logs can be shipped to files, log aggregators, or external services
• Structured JSON logging for production Nest APIs consumed by log pipelines (ELK, Datadog, CloudWatch)
• Keeping Nest’s familiar colored console format in development while switching to JSON/file transports in production, via the same logger configuration
• Capturing bootstrap-phase log messages (before DI is available) with createLogger() so early startup errors aren’t lost

Under The Hood

Architecture - WinstonModule (src/winston.module.ts) is a @Global() dynamic module exposing three static entry points — forRoot, forRootAsync, and createLogger — all of which delegate to factory functions in winston.providers.ts that construct the actual winston logger instance and wrap it to satisfy Nest’s LoggerService interface (log/error/warn/debug/verbose methods). winston.classes.ts and winston.utilities.ts provide the adapter class and the nestLike formatter, which reconstructs Nest’s default colored console format as a winston format function so switching loggers doesn’t change local dev output. The dependency on fast-safe-stringify protects the formatter from crashing when logged objects contain circular references.

Tech Stack - TypeScript built with tsc, tested with Jest, linted with ESLint; peer dependencies on @nestjs/common/@nestjs/core and a direct dependency on winston itself plus fast-safe-stringify for safe object serialization in log formatting. A sample/ directory provides a runnable example Nest app demonstrating setup.

Code Quality - Two spec files (winston.module.spec.ts, winston.utilities.spec.ts) cover module registration and the custom formatting utilities under Jest. The module surface is small (module, providers, interfaces, constants, classes, utilities each in their own file), keeping the wrapper thin and auditable rather than reimplementing winston behavior.

API Design - The three static methods mirror the same forRoot/forRootAsync convention used across the Nest ecosystem (config modules, TypeORM, etc.), so developers already familiar with Nest’s dynamic-module pattern need no new concepts. createLogger() addressing the pre-bootstrap logging gap is a deliberate ergonomic addition beyond a bare winston wrapper, and the nestLike formatter specifically targets the common complaint that swapping loggers usually means losing Nest’s readable dev console output.