@shinijs/logger

Pino-based structured logger for NestJS applications with file rotation and pretty printing

📚 Full Documentation | API Reference | Examples

Features

✅ Pino-based - Fast, low-overhead structured logging
✅ NestJS Integration - Seamless integration with NestJS ecosystem
✅ Pretty Printing - Beautiful console output in development
✅ File Rotation - Automatic daily log file rotation
✅ Configurable - Environment-based configuration
✅ TypeScript - Full type safety
✅ Context Support - Scoped logging with context

Installation

pnpm add @shinijs/logger pino pino-pretty pino-roll

Peer Dependencies

This package requires the following peer dependencies to be installed in your project:

Package	Version	Required
`@nestjs/common`	`^11.0.0`	Yes
`@nestjs/config`	`^4.0.0`	Yes
`pino`	`^10.0.0`	Yes
`pino-pretty`	`^13.0.0`	Yes
`pino-roll`	`^4.0.0`	Yes
`reflect-metadata`	`^0.2.0`	Yes

Install all peer dependencies:

pnpm add @nestjs/common@^11.0.0 @nestjs/config@^4.0.0 pino@^10.0.0 pino-pretty@^13.0.0 pino-roll@^4.0.0 reflect-metadata@^0.2.0

Note: If you're already using NestJS, you likely have @nestjs/common, @nestjs/config, and reflect-metadata installed. You only need to ensure pino, pino-pretty, and pino-roll are present.

Quick Start

1. Import the Module

import { LoggerModule } from '@shinijs/logger';

@Module({
  imports: [LoggerModule],
  // ...
})
export class AppModule {}

2. Use the Logger

import { CustomLogger } from '@shinijs/logger';

@Injectable()
export class YourService {
  constructor(private readonly logger: CustomLogger) {
    this.logger.setContext('YourService');
  }

  doSomething() {
    this.logger.log('Doing something');
    this.logger.error('Something went wrong', { error: 'details' });
  }
}

Configuration

Set environment variables:

# Log level: trace, debug, info, warn, error, fatal
LOG_LEVEL=info

# Pretty print in development
LOG_PRETTY_PRINT=true

# File logging
LOG_FILE_ENABLED=true
LOG_FILE_PATH=./logs

API Reference

CustomLogger

Main logger service implementing NestJS LoggerService.

Methods:

// Set logging context
setContext(context: string): void

// Log levels
log(message: string, metadata?: object): void
error(message: string, metadata?: object): void
warn(message: string, metadata?: object): void
debug(message: string, metadata?: object): void
verbose(message: string, metadata?: object): void

LoggerFactory

Factory for creating context-bound loggers. The ContextBoundLogger implements NestJS LoggerService for full compatibility.

import { LoggerFactory } from '@shinijs/logger';

@Injectable()
export class MyService {
  private readonly logger = LoggerFactory.createLogger('MyService');

  doWork() {
    this.logger.log('Working...');
    // ContextBoundLogger implements LoggerService, so it works with NestJS's standard logger interface
  }
}

Examples

Basic Logging

import { CustomLogger } from '@shinijs/logger';

@Injectable()
export class UserService {
  constructor(private readonly logger: CustomLogger) {
    this.logger.setContext('UserService');
  }

  async createUser(data: CreateUserDto) {
    this.logger.log('Creating user', { email: data.email });

    try {
      const user = await this.userRepository.create(data);
      this.logger.log('User created successfully', { userId: user.id });
      return user;
    } catch (error) {
      this.logger.error('Failed to create user', { error, email: data.email });
      throw error;
    }
  }
}

Using Logger Factory

import { LoggerFactory } from '@shinijs/logger';

export class SomeClass {
  private readonly logger = LoggerFactory.createLogger('SomeClass');

  process() {
    this.logger.debug('Processing started');
    // ... your logic
    this.logger.debug('Processing completed');
  }
}

Structured Logging

this.logger.log('Request processed', {
  method: 'POST',
  path: '/api/users',
  statusCode: 201,
  duration: 45,
  userId: '123',
});

Integrating with Rate Limit Module

Use the logger with @shinijs/rate-limit for consistent logging:

import { Module, Global } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { LoggerModule, LoggerFactory } from '@shinijs/logger';
import { RateLimitModule } from '@shinijs/rate-limit';

// Token for RateLimit logger provider
export const RATE_LIMIT_LOGGER_TOKEN = Symbol('RATE_LIMIT_LOGGER');

// Create a global module to provide the logger token
@Global()
@Module({
  providers: [
    {
      provide: RATE_LIMIT_LOGGER_TOKEN,
      useFactory: (loggerFactory: LoggerFactory) => {
        return loggerFactory.createLogger('RateLimit');
      },
      inject: [LoggerFactory],
    },
  ],
  exports: [RATE_LIMIT_LOGGER_TOKEN],
})
class RateLimitLoggerModule {}

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    LoggerModule,
    RateLimitLoggerModule,
    RateLimitModule.forRoot({
      loggerToken: RATE_LIMIT_LOGGER_TOKEN,
    }),
  ],
})
export class AppModule {}

Configuration Options

Environment Variables

Variable	Description	Default
`LOG_LEVEL`	Minimum log level	`info`
`LOG_PRETTY_PRINT`	Enable pretty console output	`false`
`LOG_FILE_ENABLED`	Enable file logging	`false`
`LOG_FILE_PATH`	Directory for log files	`./logs`
`LOG_FILE_ROTATION_ENABLED`	Enable automatic log file rotation	`true`*
`LOG_FILE_ROTATION_FREQUENCY`	Rotation frequency: `daily`, `hourly`, `custom`	`daily`
`LOG_FILE_ROTATION_PATTERN`	Date pattern for rotated filenames	`YYYY-MM-DD`
`LOG_FILE_MAX_FILES`	Number of log files to retain	`7`
`LOG_FILE_SIZE_LIMIT`	Maximum file size before rotation	`10M`

* Rotation is enabled by default when LOG_FILE_ENABLED=true. Set to false to use a single log file without rotation.

Log Levels

From lowest to highest priority:

trace - Very detailed debugging
debug - Debugging information
info - Informational messages (default)
warn - Warning messages
error - Error messages
fatal - Fatal errors

File Logging

When file logging is enabled, logs are written to files in the specified directory with automatic rotation and cleanup.

Basic Configuration

LOG_FILE_ENABLED=true
LOG_FILE_PATH=./logs

Key Features:

File logging works simultaneously with pretty printing - you can have both console output and file logging in development
Directory is created automatically if it doesn't exist
Automatic log file rotation enabled by default
Old log files are automatically cleaned up based on retention policy

Log Rotation

Log rotation is enabled by default when file logging is enabled. This prevents log files from growing indefinitely and helps manage disk space.

Daily Rotation (Default)

LOG_FILE_ENABLED=true
LOG_FILE_PATH=./logs
LOG_FILE_ROTATION_FREQUENCY=daily
LOG_FILE_MAX_FILES=7

File naming pattern: app-YYYY-MM-DD.log

Example files:

logs/
├── app-2024-01-15.log  (today)
├── app-2024-01-14.log
├── app-2024-01-13.log
├── app-2024-01-12.log
├── app-2024-01-11.log
├── app-2024-01-10.log
└── app-2024-01-09.log  (oldest, will be deleted when new day starts)

Automatic cleanup: When the 8th day arrives, the oldest file (app-2024-01-09.log) is automatically deleted, keeping only the most recent 7 days of logs.

Hourly Rotation

For high-traffic applications or more granular log management:

LOG_FILE_ENABLED=true
LOG_FILE_PATH=./logs
LOG_FILE_ROTATION_FREQUENCY=hourly
LOG_FILE_ROTATION_PATTERN=YYYY-MM-DD-HH
LOG_FILE_MAX_FILES=24

File naming pattern: app-YYYY-MM-DD-HH.log

Example files:

logs/
├── app-2024-01-15-14.log  (current hour)
├── app-2024-01-15-13.log
├── app-2024-01-15-12.log
└── ... (keeps last 24 hours)

Size-Based Rotation

Rotate logs when they reach a specific size:

LOG_FILE_ENABLED=true
LOG_FILE_PATH=./logs
LOG_FILE_SIZE_LIMIT=50M  # Rotate when file reaches 50MB

Supported size units: K (kilobytes), M (megabytes), G (gigabytes)

Disabled Rotation

To use a single log file without rotation (legacy behavior):

LOG_FILE_ENABLED=true
LOG_FILE_PATH=./logs
LOG_FILE_ROTATION_ENABLED=false

File naming: app.log (single file, grows indefinitely)

Use case: Suitable when you have external log management tools or limited logging needs.

Rotation Configuration Reference

Setting	Options	Description
Frequency	`daily`, `hourly`, `custom`	How often to create new log files
Pattern	Date format string	Filename pattern (e.g., `YYYY-MM-DD`, `YYYY-MM-DD-HH`)
Max Files	Number (e.g., `7`, `24`, `30`)	Number of log files to keep before deleting oldest
Size Limit	Size string (e.g., `10M`, `50M`, `1G`)	Maximum file size before rotation

Complete Example

Production configuration with daily rotation and 30-day retention:

# Basic logging
LOG_LEVEL=info
LOG_PRETTY_PRINT=false

# File logging with rotation
LOG_FILE_ENABLED=true
LOG_FILE_PATH=/var/log/myapp

# Rotation settings
LOG_FILE_ROTATION_ENABLED=true
LOG_FILE_ROTATION_FREQUENCY=daily
LOG_FILE_ROTATION_PATTERN=YYYY-MM-DD
LOG_FILE_MAX_FILES=30
LOG_FILE_SIZE_LIMIT=100M

This configuration will:

Create daily log files: app-2024-01-15.log, app-2024-01-14.log, etc.
Keep the last 30 days of logs
Rotate early if a file exceeds 100MB
Automatically delete logs older than 30 days

Development vs Production

Development (with LOG_PRETTY_PRINT=true):

14:23:45 INFO  [UserService] Creating user
14:23:45 INFO  [UserService] User created successfully

Production (JSON output):

{"level":30,"time":1699999999,"context":"UserService","msg":"Creating user","email":"user@example.com"}
{"level":30,"time":1700000000,"context":"UserService","msg":"User created successfully","userId":"123"}

Testing

# Unit tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage
pnpm test:cov

Documentation

📚 Full Documentation is available with:

Complete API reference
Configuration guide
Usage examples
Best practices
Advanced patterns

Contributing

Contributions are welcome! Please read our Contributing Guide and Code of Conduct before submitting pull requests.

Quick Start for Contributors

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests and linting (pnpm test && pnpm lint:check)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

For detailed guidelines, see CONTRIBUTING.md.

License

MIT © Shironex

Name		Name	Last commit message	Last commit date
Latest commit History 93 Commits
.changeset		.changeset
.github		.github
docs		docs
src		src
.editorconfig		.editorconfig
.gitignore		.gitignore
.lintstagedrc.json		.lintstagedrc.json
.npmignore		.npmignore
.prettierrc		.prettierrc
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
jest.config.js		jest.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

License

shinijs/logger

Folders and files

Latest commit

History

Repository files navigation

@shinijs/logger

Features

Installation

Peer Dependencies

Quick Start

1. Import the Module

2. Use the Logger

Configuration

API Reference

CustomLogger

LoggerFactory

Examples

Basic Logging

Using Logger Factory

Structured Logging

Integrating with Rate Limit Module

Configuration Options

Environment Variables

Log Levels

File Logging

Basic Configuration

Log Rotation

Daily Rotation (Default)

Hourly Rotation

Size-Based Rotation

Disabled Rotation

Rotation Configuration Reference

Complete Example

Development vs Production

Testing

Documentation

Contributing

Quick Start for Contributors

License

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors 4

Uh oh!

Languages

Packages