Configuration

Logluxe is highly configurable. This page covers all available options.

Creating a Configured Logger

import { createLogger } from 'logluxe';

const log = createLogger({
  // Configuration options
});

Configuration Options

level

Set the minimum log level to display:

const log = createLogger({
  level: 'info'  // Only show info, warn, error (hide debug)
});

log.debug('Hidden');  // Not displayed
log.info('Shown');    // Displayed
log.error('Shown');   // Displayed

Log Levels

ℹℹ Shown

✖✖ Shown

(debug is hidden at 'info' level)

Available levels (in order of priority):

• 'debug' - Show all logs
• 'info' - Show info, warn, error
• 'warn' - Show warn, error
• 'error' - Show only errors
• 'silent' - Show nothing

// Development: show everything
const devLog = createLogger({ level: 'debug' });

// Production: only important stuff
const prodLog = createLogger({ level: 'warn' });

// Testing: silence logs
const testLog = createLogger({ level: 'silent' });

🎮 Try Log Levels

// With level: 'info' log.debug('This is hidden'); log.info('This is shown'); log.warn('This is shown'); log.error('This is shown');

colors

Enable or disable color output:

// Force colors off
const log = createLogger({ colors: false });

// Force colors on (override detection)
const log = createLogger({ colors: true });

// Auto-detect (default)
const log = createLogger({ colors: 'auto' });

Environment-aware color config:

const log = createLogger({
  colors: process.env.NO_COLOR ? false : 'auto'
});

timestamp

Add timestamps to log messages:

// Enable timestamps
const log = createLogger({ timestamp: true });

log.info('Hello');
// Output: [2024-01-15T10:30:45.123Z] ℹ Hello

Timestamped Output

[2024-01-15T10:30:45.123Z]

ℹℹ Hello

[2024-01-15T10:30:45.456Z]

✔✔ Success

[2024-01-15T10:30:45.789Z]

✖✖ Error

Custom timestamp format:

const log = createLogger({
  timestamp: true,
  timestampFormat: 'HH:mm:ss'  // Short format
});

log.info('Hello');
// Output: [10:30:45] ℹ Hello

Short Timestamp

[10:30:45]

ℹℹ Hello

Timestamp options:

const log = createLogger({
  timestamp: {
    enabled: true,
    format: 'ISO',        // 'ISO' | 'locale' | 'unix' | custom format
    color: 'gray',        // Color for timestamp
    position: 'start'     // 'start' | 'end'
  }
});

prefix

Add a prefix to all log messages:

const log = createLogger({ prefix: '[MyApp]' });

log.info('Started');
// Output: [MyApp] ℹ Started

Prefixed Output

[MyApp]

ℹℹ Started

[MyApp]

✔✔ Ready

[MyApp]

⚠⚠ Memory usage high

Styled prefix:

const log = createLogger({
  prefix: {
    text: 'SERVER',
    color: 'cyan',
    bold: true,
    background: 'black'
  }
});

Styled Prefix

SERVER

ℹℹ Listening on port 3000

🎮 Try Prefix

// With prefix: '[MyApp]' log.info('Application started'); log.success('Database connected'); log.warn('Using default config');

icons

Customize icons for each log level:

const log = createLogger({
  icons: {
    success: '✓',
    error: '✗',
    warning: '⚠',
    info: 'ℹ',
    debug: '🔍'
  }
});

Emoji icons:

const log = createLogger({
  icons: {
    success: '🎉',
    error: '💥',
    warning: '⚡',
    info: '💡',
    debug: '🐛'
  }
});

Emoji Icons

🎉 Build complete!

💥 Critical error occurred

⚡ Rate limit approaching

💡 Server running on port 3000

🐛 Debug: processing 42 items

format

Customize message formatting:

const log = createLogger({
  format: (level, message, meta) => {
    return `[${level.toUpperCase()}] ${message}`;
  }
});

JSON format for production:

const log = createLogger({
  format: process.env.NODE_ENV === 'production'
    ? 'json'
    : 'pretty'
});

// In production:
log.info('Server started', { port: 3000 });
// Output: {"level":"info","message":"Server started","port":3000,"timestamp":"..."}

JSON Format (Production)

{"level":"info","message":"Server started","port":3000,"timestamp":"2024-01-15T10:30:45.123Z"}

{"level":"success","message":"Database connected","db":"postgres","timestamp":"2024-01-15T10:30:46.456Z"}

context

Add persistent context to all logs:

const log = createLogger({
  context: {
    service: 'user-api',
    version: '1.0.0',
    environment: process.env.NODE_ENV
  }
});

log.info('Request received');
// All logs include service, version, and environment

Context in Logs

{"level":"info","message":"Request received","service":"user-api","version":"1.0.0","environment":"production"}

enabled

Globally enable/disable logging:

const log = createLogger({
  enabled: process.env.NODE_ENV !== 'test'
});

Complete Configuration Example

import { createLogger, themes } from 'logluxe';

const log = createLogger({
  // Log level filtering
  level: process.env.LOG_LEVEL || 'info',
  
  // Color settings
  colors: process.env.NO_COLOR ? false : 'auto',
  
  // Timestamp configuration
  timestamp: {
    enabled: true,
    format: 'ISO',
    color: 'gray'
  },
  
  // Prefix
  prefix: {
    text: 'APP',
    color: 'cyan',
    bold: true
  },
  
  // Theme
  theme: 'dracula',
  
  // Custom icons
  icons: {
    success: '✓',
    error: '✗',
    warning: '⚠',
    info: 'ℹ',
    debug: '·'
  },
  
  // Persistent context
  context: {
    service: 'my-service',
    version: require('./package.json').version
  },
  
  // Output format
  format: process.env.NODE_ENV === 'production' ? 'json' : 'pretty',
  
  // Enable/disable
  enabled: true
});

export default log;

Full Configuration Output

[2024-01-15T10:30:45.123Z] APP

ℹℹ Server starting...

[2024-01-15T10:30:45.456Z] APP

✔✓ Database connected

[2024-01-15T10:30:45.789Z] APP

✔✓ Server ready on port 3000

Environment Variables

Logluxe respects these environment variables:

Variable	Description
NO_COLOR	Disable all colors
FORCE_COLOR	Force color output
LOG_LEVEL	Set log level
DEBUG	Enable debug mode
NODE_ENV	Affects default behaviors

# Disable colors
NO_COLOR=1 node app.js

# Force colors in CI
FORCE_COLOR=1 npm test

# Set log level
LOG_LEVEL=debug node app.js

Child Loggers

Create child loggers with inherited config:

const log = createLogger({
  prefix: 'App',
  level: 'info'
});

// Child logger inherits parent config
const dbLog = log.child({
  prefix: 'Database'
});

const apiLog = log.child({
  prefix: 'API',
  context: { component: 'api' }
});

dbLog.info('Connected');   // [Database] ℹ Connected
apiLog.info('Request');    // [API] ℹ Request

Child Loggers

[Database]

ℹℹ Connected

[API]

ℹℹ Request received

[API]

✔✔ Response sent

[Database]

●● Query executed in 45ms

🎮 Try Child Loggers

// Parent logger log.info('[App] Starting...'); // Child loggers with different prefixes log.info('[Database] Connected'); log.info('[API] Request received'); log.success('[API] Response sent');

Best Practices

1. Use Environment Variables

const log = createLogger({
  level: process.env.LOG_LEVEL || 'info',
  colors: !process.env.NO_COLOR
});

2. Different Configs for Different Environments

const config = {
  development: {
    level: 'debug',
    timestamp: true,
    colors: true
  },
  production: {
    level: 'info',
    format: 'json',
    timestamp: true
  },
  test: {
    level: 'silent'
  }
};

const log = createLogger(config[process.env.NODE_ENV] || config.development);

3. Centralize Logger Configuration

// lib/logger.ts
import { createLogger } from 'logluxe';

export const log = createLogger({
  // Central configuration
});

// Use throughout app
import { log } from './lib/logger';

4. Use Child Loggers for Modules

// Keep parent config, add module context
const moduleLog = log.child({ prefix: 'ModuleName' });

---

Next: CLI Application Example →