Skip to main content
Version: Next

ColorHandler

Beautiful ANSI color-coded console output for development.

Overview​

ColorHandler provides colorful console output with automatic coloring based on log levels. Makes your development logs easy to read and debug.

Basic Usage​

import { New, ColorHandler, Level, String, Int } from '@omdxp/jslog';

const logger = New(new ColorHandler());

logger.debug('Debug message', String('key', 'value'));  // Gray
logger.info('Info message', Int('count', 42));          // Blue
logger.warn('Warning message');                          // Yellow
logger.error('Error message');                           // Red

Configuration Options​

interface ColorHandlerOptions {
  level?: Level;              // Minimum log level (default: DEBUG)
  addSource?: boolean;        // Add source location (default: false)
  replaceAttr?: (groups: string[], attr: Attr) => Attr;
}

Color Scheme​

Default colors by level:

LevelColorANSI Code
DEBUGGray\x1b[90m
INFOBlue\x1b[34m
WARNYellow\x1b[33m
ERRORRed\x1b[31m

Development vs Production​

Use ColorHandler for development and switch to JSONHandler for production:

import { New, ColorHandler, JSONHandler } from '@omdxp/jslog';

const isDev = process.env.NODE_ENV === 'development';

const logger = New(
  isDev 
    ? new ColorHandler() 
    : new JSONHandler()
);

Example Output​

import { New, ColorHandler, String, Int, Bool } from '@omdxp/jslog';

const logger = New(new ColorHandler());

logger.info(
  'User login',
  String('username', 'alice'),
  String('ip', '192.168.1.1'),
  Bool('success', true)
);

Output (in color):

2024-01-15 10:30:45 INFO User login username=alice ip=192.168.1.1 success=true

Combining with Other Features​

With File Handler​

Use MultiHandler to write colorful logs to console and plain logs to file:

import { New, ColorHandler, FileHandler, MultiHandler } from '@omdxp/jslog';

const logger = New(new MultiHandler([
  new ColorHandler(),                           // Colorful console
  new FileHandler({ filepath: './logs/app.log' })  // Plain file logs
]));

With Middleware​

Add middleware for enrichment:

import { 
  New, 
  MiddlewareHandler, 
  ColorHandler,
  timestampMiddleware,
  hostnameMiddleware 
} from '@omdxp/jslog';

const logger = New(new MiddlewareHandler({
  handler: new ColorHandler(),
  middleware: [
    timestampMiddleware(),
    hostnameMiddleware()
  ]
}));

Best Practices​

Do:

  • Use ColorHandler in development for easy debugging
  • Switch to JSONHandler in production for machine-parseable logs
  • Combine with MultiHandler to output to multiple destinations

Don't:

  • Use ColorHandler in production (ANSI codes interfere with log aggregators)
  • Pipe colored output to files (colors are for terminals only)

See Also​