LoggerJS is a monorepo of logging packages around a dependency-free, platform-neutral core. The same logger code runs in Node, browsers, workers, and edge runtimes. It is organized around three user-facing concepts plus one boundary rule:

• Integrations collect logs automatically from platform behavior — browser console calls, script errors, fetch/XHR failures, Web Vitals, route changes, Node process crashes, HTTP servers, serverless handlers, queue and database clients. All opt-in.
• Middleware / processors synchronously enrich, redact, sample, dedupe, rate-limit, fingerprint, buffer (fingers-crossed), route, and tag logs before delivery. Middleware run on raw records; processors run on projected events.
• Transports deliver logs anywhere — console, pretty DevTools/terminal output, stdout, files, HTTP, IndexedDB, WebSocket, service workers, worker threads, OTLP, Sentry, Datadog, Elasticsearch, Loki, CloudWatch, SQL databases — with reusable batching, retry, backoff, and circuit-breaker wrappers where the destination needs them.
• Codecs belong to transports. The pipeline keeps values raw; each destination owns its serialization. Built-in codecs are fast by default and never lose a log to an encoding error.

Table of Contents

• Install
• AI Skill
• Quick Start
  • Node
  • Browser
  • Library authors
• How It Works
• Typed Events
• Context Propagation
• Performance
• Packages
• The Ecosystem
• How It Compares
• Documentation
• Development
• License

Install

Pick the package for your platform. Each platform package re-exports all of @loggerjs/core, so one install per app is enough to start.

# Node services
npm install @loggerjs/node @loggerjs/processors

# Browser apps
npm install @loggerjs/browser @loggerjs/processors

_{Using pnpm or yarn? Swap npm install for pnpm add / yarn add. Add vendor packages (@loggerjs/otel, @loggerjs/sentry, @loggerjs/datadog, …) only when you deliver to that destination.}

All packages ship ESM + CJS with full TypeScript declarations and granular subpath exports (@loggerjs/node/transport-stdout, @loggerjs/browser/integration-console, …) so bundlers tree-shake to exactly what you import.

AI Skill

LoggerJS includes an installable AI skill for coding agents. Use it when you want an agent to add LoggerJS to a JavaScript or TypeScript app, choose the right runtime packages, configure production logging, or migrate from console, pino, winston, loglevel, debug, or an existing wrapper.

# Install the LoggerJS skill
npx skills add jskits/loggerjs --skill loggerjs

# Install it for a specific agent
npx skills add jskits/loggerjs --skill loggerjs --agent codex
npx skills add jskits/loggerjs --skill loggerjs --agent claude-code

# Use it once without installing
npx skills use jskits/loggerjs --skill loggerjs

Then ask your agent:

Use $loggerjs to add production-ready structured logging to this Node API.

The skill lives in skills/loggerjs, and the full usage guide is in docs/AI-SKILL.md.

Quick Start

Node

import {
  captureProcessIntegration,
  createLogger,
  stdoutTransport,
} from "@loggerjs/node";
import { redactProcessor } from "@loggerjs/processors";

const logger = createLogger({
  category: ["api"],
  level: "info",
  tags: { service: "checkout", env: process.env.NODE_ENV ?? "dev" },
  processors: [redactProcessor({ keys: ["password", /token/i] })],
  transports: [stdoutTransport()],
  integrations: [captureProcessIntegration()],
});

logger.info("order created", { orderId: "ord_123" });
logger.error(new Error("card declined"), "payment failed", {
  orderId: "ord_123",
});

await logger.flush();

stdoutTransport() writes one NDJSON line per log; captureProcessIntegration() turns uncaught exceptions, unhandled rejections, and process warnings into structured events automatically.

Browser

import {
  browserHttpTransport,
  captureBrowserErrorsIntegration,
  captureConsoleIntegration,
  captureFetchIntegration,
  createLogger,
  memoryBrowserHttpOfflineQueue,
  pageLifecycleIntegration,
} from "@loggerjs/browser";
import { redactProcessor } from "@loggerjs/processors";

const logger = createLogger({
  category: ["web"],
  level: "info",
  processors: [redactProcessor()],
  transports: [
    browserHttpTransport({
      url: "/api/logs",
      offlineQueue: memoryBrowserHttpOfflineQueue({ maxEntries: 500 }),
      useBeaconOnPageHide: true,
    }),
  ],
  integrations: [
    captureConsoleIntegration({ levels: ["warn", "error"] }),
    captureBrowserErrorsIntegration(),
    captureFetchIntegration(),
    pageLifecycleIntegration(),
  ],
});

logger.info("page loaded");

Logs batch over HTTP, queue while offline, replay with backoff when the network returns, and attempt a best-effort sendBeacon flush when the tab closes.

Library authors

// inside your library — silent until the app configures it
import { getLogger } from "@loggerjs/core";

const logger = getLogger(["my-lib", "client"]);
logger.debug("handshake started"); // no-op until configure() runs

// inside the application
import { configure } from "@loggerjs/core";
import { stdoutTransport } from "@loggerjs/node";

await configure({
  transports: { stdout: stdoutTransport() },
  loggers: [{ category: ["my-lib"], level: "warn", transports: ["stdout"] }],
});

How It Works

Every log flows through one pipeline. The hot path is engineered to do as little as possible until a value is actually needed.

  logger.info("order created", { orderId })
        │
        ▼  level gate ──── disabled levels stop here (~5ns, no allocation)
        │
  ┌─────────────┐   lazy message · raw error · shared ctx/tags · no id yet
  │  LogRecord  │
  └──────┬──────┘
         │
   middleware ───────── sync · ordered · enrich / redact / drop on raw records
         │
   any processors? ──no──▶  record fast path — straight to transports, no projection
         │ yes
         ▼
  ┌─────────────┐   id assigned · message resolved · error normalized
  │  LogEvent   │
  └──────┬──────┘
         │
   processors ───────── sample · dedupe · fingerprint · route · fingers-crossed
         │
         ▼
   transports ───────── console · stdout · file · http · indexeddb · otlp · sentry · …
         │               shared batching · retry · backoff · circuit breaker
         ▼
   codec ────────────── each destination owns its serialization (fast, never throws)

LogRecord is the hot-path shape — it keeps the message function unevaluated, the error raw, and context/tags shared by reference. A logger with zero processors sends records straight to transports (the record fast path, no event projection). Adding any processor opts that logger into LogEvent projection so processors can see the resolved shape. See CONCEPTS.md for the full model.

Typed Events

Define an event once and log it with a checked payload — message and tags derive from the data.

import { defineEvent } from "@loggerjs/core";

const CheckoutCompleted = defineEvent<{ orderId: string; amountCents: number }>(
  {
    type: "checkout.completed",
    message: (event) => `checkout completed ${event.orderId}`,
    tags: { domain: "checkout" },
  },
);

logger.event(CheckoutCompleted, { orderId: "ord_123", amountCents: 4999 });

Context Propagation

Bind fields once and have them follow async execution across every await — no manual threading.

import { withContext } from "@loggerjs/core";
import { installAsyncLocalStorageContext } from "@loggerjs/node";

installAsyncLocalStorageContext(); // once at startup

await withContext({ requestId: "req_123" }, async () => {
  logger.info("request started"); // carries { requestId } across awaits
});

Performance

Reference machine: Apple M1 Max (64 GB), Node v22.21.1, against pino 10.3.1 / winston 3.19.0 / LogTape 2.1.3. The loggerjs-vs-pino rows use the drift-canceling paired A/B harness (BENCH_AB, 22 runs); competitor rows are the sequential suite. Full methodology and the regression gate live in docs/BENCHMARKS.md, with checked-in machine evidence in docs/BENCHMARK-MATRIX.md.

The hot path is deliberate: level gating before any allocation, lazy message resolution, frozen shared tags, memoized ids, a record fast path that skips event projection, and fragment-cached serialization — all guarded by pnpm bench:gate in CI. On the M1 Max reference, loggerjs lean and prepared edge out pino in paired A/B runs, but the ranking is CPU/V8-dependent; reproduce it on your own machine with BENCH_AB=1 pnpm bench:node and add broader evidence through the benchmark matrix. LoggerJS keeps one record per log so middleware, integrations, and multiple transports can observe it, and reaches pino's class without giving that pipeline up — see the architecture note.

Packages

Vendor HTTP transports speak wire protocols directly; SDK/provider adapters use the SDK object or provider your app already owns. No vendor SDKs are bundled.

The Ecosystem

import { createLogger } from "@loggerjs/core";
import { indexedDbTransport } from "@loggerjs/browser/transport-indexeddb";
import { downloadBlob, exportLogsToZip } from "@loggerjs/browser/export-zip";
import { privacyGuardProcessor, redactProcessor } from "@loggerjs/processors";

const supportStore = indexedDbTransport({
  dbName: "my-app-support-logs",
  localStorageSpill: { namespace: "my-app-support-logs" },
});

const logger = createLogger({
  category: ["web"],
  processors: [redactProcessor(), privacyGuardProcessor()],
  transports: [supportStore],
});

export async function downloadSupportLogs() {
  await logger.flush();
  downloadBlob(
    await exportLogsToZip(supportStore, {
      groupBySession: true,
      includeRecent: true,
      query: { order: "asc" },
    }),
    "support-logs.zip",
  );
}

How It Compares

LoggerJS shines when the logging problem spans browser and server collection from one mental model — and when you want logs delivered to your own destinations (HTTP, files, your DB, Loki/Elasticsearch, OTLP) rather than a single vendor's SaaS, from a zero-dependency core that runs under strict CSP, on edge/Workers, and offline. A fair, repo-sourced snapshot (full matrix and sources in docs/COMPARISON.md):

On the direct Node JSON path loggerjs and pino are in the same class — on the M1 Max reference loggerjs lean is ~1.19× pino, while on other CPUs pino can lead (it's CPU/V8-dependent; reproduce with BENCH_AB; see the checked-in benchmark matrix). LoggerJS reaches that throughput while adding a record pipeline that works the same in the browser, captures automatically, and delivers reliably.

Documentation

Runnable examples live in examples/: Node basics, browser basics, OpenTelemetry, Sentry.

Development

Use Node >=22.13 for repository development and the full pnpm check gate. Published packages are smoke-tested as packed consumers on Node 20.19, 22, and 24; Node 20.19 is the runtime compatibility floor, not the repo toolchain floor.

pnpm install
pnpm check        # format, lint, typecheck, test, build, size budgets, API reports, pack checks
pnpm bench        # node + browser benchmarks
pnpm bench:gate   # performance regression gate (also runs in CI)

See docs/CONTRIBUTING.md for conventions and the rules CI enforces.

License

MIT © JS Kits