Logger

Production-grade, platform-independent logging for JavaScript & TypeScript. Works in React Native, Node.js, and the browser — zero runtime dependencies.

Why

Most loggers are either too simple (no structure, no transports) or too heavy (Node-only, tons of deps). This one is neither.

• Only logs. Never stores. Never sends.
• Your app decides where logs go via pluggable transports.
• Same API across React Native, Node, and the browser.
• Zero runtime dependencies.

Features

| | | |---|---| | 5 log levels | debug · info · warn · error · fatal | | Structured logging | Attach typed metadata objects to every log entry | | Child loggers | Scope a logger to a module or request — context stamps every line | | Pluggable transports | Console, batch, or write your own in ~10 lines | | Smart defaults | Pretty output in dev, JSON in production — auto-detected | | Singleton | One instance across your entire app, no prop-drilling | | BatchTransport | Buffer logs and flush in one batch instead of per-line HTTP calls | | Per-transport level filtering | Console shows debug; Sentry only gets error and above | | Graceful shutdown | flush() ensures buffered logs are sent before process exit | | Zero dependencies | Nothing in node_modules that you didn't ask for |

Install

npm install @devraj-labs/logger
# or
yarn add @devraj-labs/logger

Quick Start

import { createLogger } from "@devraj-labs/logger";

// Call once at your app entry point
const logger = createLogger({ level: "info" });

logger.info("Server started", { port: 3000 });
logger.warn("Disk usage high", { usedPercent: 91 });
logger.error("Request failed", { path: "/api/user", statusCode: 500 });

Call createLogger() with no arguments anywhere else — it returns the same singleton.

// some-other-file.ts
const logger = createLogger(); // same instance, no config needed

Setup by Platform

Node / Express

// src/index.ts
const logger = createLogger({ level: "info" });

React Native

// App.tsx
import { createLogger, ConsoleTransport } from "@devraj-labs/logger";

createLogger({
  level:      __DEV__ ? "debug" : "warn",
  transports: [new ConsoleTransport({ format: __DEV__ ? "pretty" : "json" })],
});

Child Loggers

Scope a logger to a module or request. All context fields are stamped on every log line automatically.

const logger = createLogger();

// Module-scoped
const log = logger.child({ module: "AuthService" });
log.info("Token issued", { userId: "u_123" });
// → { module: "AuthService", userId: "u_123", message: "Token issued", ... }

// Request-scoped (nest deeper)
const reqLog = log.child({ requestId: "req_abc" });
reqLog.debug("Cache miss");
// → { module: "AuthService", requestId: "req_abc", message: "Cache miss", ... }

Log Levels

logger.debug("DB query", { sql: "SELECT ..." });   // internal details
logger.info("User signed in", { userId: "u_1" });  // normal events
logger.warn("Rate limit approaching", { pct: 80 }); // degraded but alive
logger.error("Payment failed", { orderId: "o_9" }); // operation failed
logger.fatal("Out of memory");                       // app about to crash

| Level | Numeric | When to use | |---------|---------|-------------| | debug | 0 | Internal details — queries, state changes | | info | 1 | Normal events — server started, user logged in | | warn | 2 | Something looks wrong but app is still running | | error | 3 | A request or operation failed | | fatal | 4 | App is about to crash | | silent| 5 | Disables all output |

Change the level at runtime:

logger.setLevel("warn"); // drop debug + info from here on

Transports

The logger never stores or sends anything itself. Transports decide what happens to each log entry.

Your Code → Logger (level gate) → ConsoleTransport   (prints to terminal)
                                → BatchTransport      (buffers → POST to server)
                                → YourCustomTransport (AsyncStorage / Sentry / file / anything)

ConsoleTransport

Added automatically if you don't specify any transports. Prints pretty output in dev, JSON in production.

import { ConsoleTransport } from "@devraj-labs/logger";

createLogger({
  transports: [
    new ConsoleTransport({ format: "pretty" }), // or "json" | "auto"
  ],
});

| Option | Type | Default | Description | |--------|------|---------|-------------| | format | "pretty" \| "json" \| "auto" | "auto" | Output format. "auto" picks pretty in dev, JSON in production | | fatalMethod | "error" \| "warn" \| "log" | "error" | Which console method is used for fatal entries |

BatchTransport

Buffers logs in memory and sends them in one batch. Avoids one HTTP call per log line.

import { BatchTransport } from "@devraj-labs/logger";

createLogger({
  transports: [
    new BatchTransport({
      sendBatch: async (entries) => {
        await fetch("/api/logs", {
          method: "POST",
          body: JSON.stringify(entries),
        });
      },
      maxBatchSize: 50,
      flushIntervalMs: 5000,
    }),
  ],
});

Custom Transport

Implement { name, log(entry) } — that's the whole interface.

import { Transport, LogEntry } from "@devraj-labs/logger";

class SentryTransport implements Transport {
  name = "sentry";
  minLevel = LogLevel.ERROR; // only errors and above

  log(entry: LogEntry): void {
    Sentry.captureMessage(entry.message, {
      level: entry.levelName,
      extra: entry.meta,
    });
  }
}

createLogger({
  transports: [new ConsoleTransport(), new SentryTransport()],
});

Per-transport level filtering

createLogger({
  level: "debug", // root logger emits everything
  transports: [
    new ConsoleTransport(),                              // sees all levels
    new SentryTransport({ minLevel: LogLevel.ERROR }),   // only errors+
  ],
});

Graceful Shutdown

If BatchTransport holds unsent logs when the process exits, they're lost. Call flush() before exiting.

process.on("SIGTERM", async () => {
  await logger.flush(); // drains all transport buffers
  process.exit(0);
});

Environment Defaults

| NODE_ENV | Default level | Console format | |---------------|---------------|------------------| | development | debug | pretty (colours) | | production | warn | JSON | | unset | debug | pretty |

Override at any time:

createLogger({ level: "info", forceJsonOutput: true });

API Reference

createLogger(config?)

Returns the singleton Logger. Config only applies on the first call.

| Option | Type | Default | Description | |--------|------|---------|-------------| | level | LogLevelName | env-detected | Minimum level to emit | | transports | Transport[] | [ConsoleTransport] | Active transports | | context | LogContext | {} | Global context merged into every entry | | forceJsonOutput | boolean | false | Force JSON format regardless of env |

Logger

| Method | Description | |--------|-------------| | debug / info / warn / error / fatal(msg, meta?) | Emit a log entry | | child(context) | Create a scoped child logger | | setLevel(level) | Change minimum level at runtime | | getLevel() | Returns current level name | | addTransport(transport) | Register a transport | | removeTransport(name) | Remove a transport by name (calls flush) | | setContext(context) | Merge context into root logger | | flush() | Drain all transport buffers |

Examples

| # | What it covers | File | |---|----------------|------| | 1 | All 5 log levels and terminal output | 01-basic-logging.ts | | 2 | setLevel() — which logs are dropped vs shown | 02-level-filtering.ts | | 3 | Child loggers — module name, nested request context | 03-child-logger.ts | | 4 | Production JSON output format | 04-json-output.ts | | 5 | Writing a custom transport, per-transport minLevel | 05-custom-transport.ts | | 6 | BatchTransport — buffer logs, send in one go | 06-batch-transport.ts | | 7 | flush() — don't lose logs on process exit | 07-flush-on-shutdown.ts | | 8 | Singleton — sharing one logger across multiple files | 08-singleton-across-files.ts |

License

MIT © devraj-labs