@nextrush/log

Universal logging for modern JavaScript.

Zero dependencies • Tree-shakeable • Production-ready

Node.js • Bun • Deno • Browser • React • Next.js • Edge

Why @nextrush/log?

• 🎯 One config controls ALL loggers — Singleton pattern for 100+ file projects
• 🚀 Zero dependencies — No bloat, no supply chain risk
• 🌍 Universal — Same API everywhere (Node, Browser, Edge, React)
• 🔒 Production-safe — Auto-redaction, JSON output, level filtering
• 📦 Tiny — Tree-shakeable, minimal bundle impact
• 🧪 Well-tested — 89%+ coverage, 194 tests

📖 Documentation · 🔧 API Reference · ❓ FAQ

Install

npm install @nextrush/log

Quick Start

import { createLogger } from '@nextrush/log';

const log = createLogger('MyApp');

log.info('Server started', { port: 3000 });
log.warn('High memory', { used: '85%' });
log.error('Failed', new Error('timeout'));

Development — Pretty, colorful output:

10:30:00 INFO  [MyApp] Server started { port: 3000 }
10:30:01 WARN  [MyApp] High memory { used: '85%' }
10:30:02 ERROR [MyApp] Failed Error: timeout

Production — JSON for log aggregators (Datadog, CloudWatch, etc.):

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

🎯 Central Control (The Killer Feature)

One line controls ALL loggers across your entire application.

// app-entry.ts — Configure ONCE at startup
import { disableLogging, configure, setGlobalLevel } from '@nextrush/log';

// Option 1: Disable ALL logging instantly
disableLogging();

// Option 2: Configure globally
configure({
  enabled: process.env.NODE_ENV !== 'test',
  minLevel: process.env.NODE_ENV === 'production' ? 'info' : 'debug',
});

// Option 3: Set global level
setGlobalLevel('error'); // Only errors across ALL loggers

How it works:

┌─────────────────────────────────────────────────────────────┐
│              Global Config (Singleton)                       │
│                                                             │
│   disableLogging()  ←── Call from ANY file, ONE time        │
│                                                             │
└─────────────────────────────────────────────────────────────┘
                              │
           Instantly affects ALL loggers
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
   file1.ts              file2.ts              file3.ts
   createLogger()        createLogger()        createLogger()
        │                     │                     │
        ▼                     ▼                     ▼
    DISABLED              DISABLED              DISABLED

No need to change 100+ files. Just configure once, all loggers obey.

Log Levels

| Level | Priority | Use Case | |-------|:--------:|----------| | trace | 10 | Detailed debugging | | debug | 20 | Development info | | info | 30 | Normal operations ← production default | | warn | 40 | Potential issues | | error | 50 | Recoverable errors | | fatal | 60 | Critical failures |

const log = createLogger('App', { minLevel: 'warn' });

log.debug('ignored');  // ❌ Below warn
log.warn('logged');    // ✅
log.error('logged');   // ✅

Environment Auto-Detection

| Setting | Development | Production | |---------|:-----------:|:----------:| | minLevel | trace | info | | Output | Pretty | JSON | | Colors | ✅ | ❌ | | Redaction | ❌ | ✅ |

// Auto-detects NODE_ENV
const log = createLogger('App');

// Or force environment
const log = createLogger('App', { env: 'production' });

Features

Namespace Filtering (Large Codebases)

import { enableNamespaces, createLogger } from '@nextrush/log';

// Only log from specific modules
enableNamespaces(['api:*', 'auth:*']);

createLogger('api:users').info('Logged');     // ✅
createLogger('db:queries').info('Ignored');   // ❌

Child Loggers

const log = createLogger('App');
const db = log.child('Database');

db.info('Connected');  // [App:Database] Connected

Request Tracing

const requestLog = log.withCorrelationId('req-abc123');
requestLog.info('Processing');
// Output includes: "correlationId": "req-abc123"

Performance Timing

const timer = log.time('db-query');
await db.query('SELECT * FROM users');
timer.end('Done', { rows: 100 });
// "Done" { duration: 42, rows: 100 }

Auto-Redaction (Production)

log.info('Login', {
  email: '[email protected]',
  password: 'secret123',  // → "[REDACTED]"
  token: 'xyz',           // → "[REDACTED]"
});

Custom Transports

import { createBatchTransport } from '@nextrush/log';

const { transport, flush } = createBatchTransport(
  async (logs) => fetch('/api/logs', {
    method: 'POST',
    body: JSON.stringify(logs)
  }),
  { batchSize: 50, flushInterval: 5000 }
);

log.addTransport(transport);

React Integration

import { LoggerProvider, useLogger } from '@nextrush/log/react';

function App() {
  return (
    <LoggerProvider
      context="MyApp"
      globalConfig={{ enabled: process.env.NODE_ENV !== 'test' }}
    >
      <MyComponent />
    </LoggerProvider>
  );
}

function MyComponent() {
  const log = useLogger('MyComponent');
  return <button onClick={() => log.info('Clicked!')}>Click</button>;
}

API Quick Reference

| Function | Description | |----------|-------------| | createLogger(name, options?) | Create a logger instance | | configure(options) | Set global configuration | | disableLogging() | Disable ALL logging globally | | enableLogging() | Re-enable logging | | setGlobalLevel(level) | Set global minimum level | | enableNamespaces(patterns) | Filter by namespace patterns | | addGlobalTransport(fn) | Add transport to ALL loggers |

| Logger Method | Description | |---------------|-------------| | log.trace/debug/info/warn/error/fatal() | Log at level | | log.child(name) | Create child logger | | log.withCorrelationId(id) | Add correlation ID | | log.time(label?) | Start performance timer | | log.setLevel(level) | Change level at runtime | | log.isLevelEnabled(level) | Check if level would log | | log.addTransport(fn) | Add custom transport |

Documentation

• 📖 Getting Started
• 🎛️ Global Configuration
• 📚 API Reference
• 💡 Examples
• ✅ Best Practices
• ❓ FAQ

License

MIT © Tanzim Hossain