console-log-json

All Contributors

console-log-json

Drop-in structured JSON logging for Node.js and the browser. Zero dependencies. No vendor lock-in. One line to set up. TypeScript types included.

Replace console.log() with production-grade JSON output – no code changes required across your entire codebase, and no logger API to couple your application to.

import { LoggerAdaptToConsole } from "console-log-json";
LoggerAdaptToConsole();

// Every console.log, console.error, console.warn, etc. now outputs structured JSON
console.log("user signed in", { userId: 42, plan: "pro" });

{"level":"info","message":"user signed in","plan":"pro","userId":42,"@timestamp":"2025-01-15T08:30:00.000Z","@filename":"src/auth/login.ts","@packageName":"my-app"}

console-log-json is built for developers who already have console.* calls throughout a codebase and want structured logs without a logger migration. Install it with npm, turn it on once, and keep shipping the same application code while getting JSON that log platforms can ingest immediately. Because it hooks the standard console API instead of making you thread a logger instance through your app, it is easy to add to an existing codebase and easy to remove later if you ever change direction.

At a Glance

Contents

Why Developers Use It

This library is a strong fit when you want structured logging to become part of the normal development flow without rewriting application code.

  console-log-json winston / pino / bunyan
Setup 1 line, drop-in Rewrite every log call
Application coupling Standard console.* API Special logger instance / library API
Dependencies Zero 5-30+ transitive deps
Browser support Yes No (Node only)
Argument handling Throw anything in any order Strict API signatures
Stack traces Automatic, single-line Manual formatting
Source file tracking Automatic @filename on every log Not built-in
Crash safety Logger errors never crash your app Depends on config

Zero dependencies

No winston. No pino. No bunyan. No transitive dependency tree to audit, no supply chain risk, no version conflicts. The entire library is self-contained.

Drop-in replacement – no code changes needed

Call LoggerAdaptToConsole() once at startup. Every console.log(), console.error(), console.warn(), console.info(), console.debug() across your entire codebase – including third-party libraries – instantly outputs structured JSON. No find-and-replace. No import changes.

That same design keeps your application code decoupled from the logger. Unlike libraries that require a dedicated logger instance such as logger.info(...), your code continues to use the platform-standard console API. If you later decide to remove console-log-json or replace it with something else, the change is typically concentrated at initialization instead of spread across the whole application.

Throw anything at it

Strings, numbers, booleans, objects, errors, circular references, null, undefined – in any order, in any combination. The logger figures it out and produces consistent, parseable JSON every time.

console.log("request failed", 500, new Error("timeout"), { endpoint: "/api/users" }, null);

{"level":"error","message":"request failed - 500  - timeout","endpoint":"/api/users","errCallStack":"Error: timeout\n    at ...","@timestamp":"..."}

Single-line JSON for log ingestion

Every log entry is a single line of JSON. Stack traces, nested objects, multi-line error messages – all flattened to one line. This is the format that log management tools like DataDog, LogDNA, Splunk, OpenSearch, CloudWatch, and ELK are designed to ingest. The output uses standard field names (level, message, @timestamp) that most tools recognize automatically or with minimal field mapping. No more multi-line log entries getting split into separate events or interleaved with other logs.

Automatic metadata on every log

Every log entry automatically includes contextual information that would be tedious and error-prone to add manually:

No manual tagging. No logger.info("msg", { file: __filename }). It just works.

Built-in structured redaction

Sensitive fields can be redacted with a Pino-style redact option using explicit object paths. This keeps secrets like passwords, bearer tokens, API keys, and cookies out of logs without relying on brittle regexes over whole log lines.

LoggerAdaptToConsole({
  redact: ['password', 'headers.authorization', 'payment.card.number']
});

Redaction is applied to the final structured log object, so it also covers fields added by transformOutput. The original objects passed to console.log(...) are not mutated.

Crash-safe by design

The logger will never crash your application. Every code path in the logging pipeline is wrapped in try/catch. If anything goes wrong during log formatting, the logger falls back silently. Your console.log() call will never throw an exception, even with the most exotic inputs.

Browser compatible

Works in Node.js and in the browser. Node-specific features (file detection) degrade gracefully instead of crashing. @filename is best-effort in the browser and may show <unknown> or a bundle path, especially when the library and app are bundled into one file. Ship the same logging code to your server and your frontend.

Performance-conscious

Quick Start

Install

npm install console-log-json

Initialize

ESM:

import { LoggerAdaptToConsole } from "console-log-json";
LoggerAdaptToConsole();

CommonJS:

const { LoggerAdaptToConsole } = require("console-log-json");
LoggerAdaptToConsole();

That’s it. Every console.log() in your codebase now outputs JSON.

In Node ESM projects, very early startup logs may be buffered briefly while @packageName is resolved from package.json, then emitted normally.

Restore original console (optional)

import { LoggerRestoreConsole } from "console-log-json";
LoggerRestoreConsole();

Common Usage Patterns

Start with the first few examples to understand the default behavior, then use the later sections as a cookbook for less common cases.

Basic message

console.log("server started on port 3000");

{"level":"info","message":"server started on port 3000","@timestamp":"2025-01-15T08:30:00.000Z","@filename":"src/index.ts","@packageName":"my-api"}

Message with context

console.log("order placed", { orderId: "ORD-123", total: 59.99, items: 3 });

{"level":"info","message":"order placed","items":3,"orderId":"ORD-123","total":59.99,"@timestamp":"..."}

Context properties are extracted to the top level and sorted alphabetically for consistent, easy-to-parse output.

Error with context

console.log("payment failed", new Error("card declined"), { customerId: "C-456", amount: 99.99 });

{"level":"error","message":"payment failed  - card declined","@errorObjectName":"Error","amount":99.99,"customerId":"C-456","errCallStack":"Error: card declined\n    at ...","@timestamp":"..."}

ErrorWithContext for richer error handling

A common frustration in production debugging: you see "connection refused" in the logs but have no idea which query, which user, or which table caused it. ErrorWithContext solves this by letting you attach structured context to errors as they bubble up through your code, without losing the original stack trace.

import { ErrorWithContext } from "console-log-json";

try {
  await db.query("SELECT * FROM users WHERE id = $1", [userId]);
} catch (err) {
  // Wrap the original error with additional context -- the original stack trace is preserved
  throw new ErrorWithContext(err, { userId, operation: "getUser", table: "users" });
}

{"level":"error","message":"connection refused","operation":"getUser","table":"users","userId":42,"errCallStack":"Error: connection refused\n    at ...\nCaused By: Error: connection refused\n    at ...","@timestamp":"..."}

Now when you see this error in your log dashboard, you can immediately filter by userId: 42 or table: "users" to understand the scope of the problem. You can nest multiple ErrorWithContext wrappings – each layer adds context, and the full causal chain is preserved with Caused By: in the stack trace.

Strings, numbers, booleans – any order

console.log("response", 200, "OK", { duration: 45 }, true);

{"level":"info","message":"response - 200 - OK - true","duration":45,"@timestamp":"..."}

Strings, numbers, and booleans are concatenated into the message. Objects are extracted as top-level properties. The order you pass them doesn’t matter.

Multiple context objects are merged

const userInfo = { firstName: "Homer", lastName: "Simpson" };
const requestInfo = { ip: "10.0.0.1", method: "POST" };
console.log("login attempt", userInfo, requestInfo);

{"level":"info","message":"login attempt","firstName":"Homer","ip":"10.0.0.1","lastName":"Simpson","method":"POST","@timestamp":"..."}

Circular references are handled safely

In real applications, objects with circular references are common – Express request objects, Mongoose documents, socket instances, DOM nodes. Most loggers choke on these with TypeError: Converting circular structure to JSON. console-log-json handles them gracefully.

const obj = { name: "test" };
obj.self = obj;
console.log("circular", obj);

{"level":"info","message":"circular","name":"test","self":"[Circular ~]","@timestamp":"..."}

Explicit log level override

Sometimes you want to use console.log() but control the log level – for example, when a function dynamically decides the severity. Pass a { level: "..." } object as any parameter.

console.log({ level: "warn" }, "disk usage at 90%", { partition: "/dev/sda1" });

{"level":"warn","message":"disk usage at 90%","partition":"/dev/sda1","@timestamp":"..."}

Supports error, err, warn, warning, info, information, http, verbose, debug, silly. Aliases like err and warning are normalized automatically.

JSON string auto-parsing

Third-party libraries and APIs often emit pre-formatted JSON strings. Rather than logging these as opaque strings (making them impossible to filter or query on individual fields), console-log-json automatically detects JSON in your messages and extracts it into a structured @autoParsedJson property.

console.log('{"event":"webhook","source":"stripe","type":"payment.succeeded"}');

{"level":"info","message":"<auto-parsed-json-string-see-@autoParsedJson-property>","@autoParsedJson":{"event":"webhook","source":"stripe","type":"payment.succeeded"},"@timestamp":"..."}

Now you can query @autoParsedJson.source = "stripe" in your log dashboard instead of doing substring searches on a raw message. This can be disabled with CONSOLE_LOG_JSON_DISABLE_AUTO_PARSE=true if you prefer the raw string.

Reserved message handling

The logger treats message as a reserved field and handles it consistently:

console.log('dude', { message: 'hi there', cont: { key: 'value' } });

{"level":"info","message":"dude - hi there","cont":{"key":"value"},"@timestamp":"..."}

console.log({ message: { key: 'value' } });

{"level":"info","message":"<no-message-was-passed-to-console-log>","@messageObject":{"key":"value"},"@timestamp":"..."}

Static properties on every log (service name, environment, etc.)

In microservice and containerized environments, SRE teams need to filter logs by service, environment, region, deployment version, or pod name. Rather than adding these to every log call, set them once at startup and they’re automatically included on every line.

LoggerAdaptToConsole({
  customOptions: {
    service: "payment-api",
    environment: "production",
    region: "us-east-1"
  }
});

console.log("health check passed");

{"level":"info","message":"health check passed","environment":"production","region":"us-east-1","service":"payment-api","@timestamp":"..."}

Now every log from this service is filterable by service: "payment-api" in DataDog, OpenSearch, or any log aggregator – without modifying a single log call across the codebase.

Nesting context under a single key (clean top-level schema)

By default, properties from context objects are flattened to the top level of the JSON output. This is great for tools like LogDNA that only filter on top-level fields, but it can be a problem for teams using DataDog, OpenSearch, or Splunk – “random” properties appearing at the top level can interfere with dashboards, alerts, and saved filters.

Set CONSOLE_LOG_JSON_CONTEXT_KEY to nest all user-provided context under a single, predictable key:

CONSOLE_LOG_JSON_CONTEXT_KEY=context

console.log('order placed', { orderId: 'ORD-1', total: 59.99 }, { items: 3 });

Without the option (default – flattened to top level):

{"level":"info","message":"order placed","items":3,"orderId":"ORD-1","total":59.99,"@timestamp":"..."}

With CONSOLE_LOG_JSON_CONTEXT_KEY=context:

{"level":"info","message":"order placed","context":{"items":3,"orderId":"ORD-1","total":59.99},"@timestamp":"..."}

Now the top level has a fixed, predictable schema: level, message, context, @timestamp, @filename, @packageName. Your DataDog filters and OpenSearch index mappings won’t break when a developer adds a new context property. You can still query individual fields with context.orderId in tools that support nested field access.

The key name is configurable – use context, data, metadata, or whatever fits your team’s conventions.

Log level filtering

Control log verbosity per environment. Set warn in production to keep logs lean, debug in staging for troubleshooting, silly in development to see everything. You can also change the level at runtime with SetLogLevel() – useful for temporarily increasing verbosity on a live service during an incident without redeploying.

LoggerAdaptToConsole({ logLevel: LOG_LEVEL.warn });

console.info("this will be suppressed");   // not logged
console.warn("this will appear");           // logged
console.error("this will appear too");      // logged

Log levels follow RFC 5424 priority (highest to lowest): error > warn > info > http > verbose > debug > silly.

Colorized output for local development

Set the environment variable:

CONSOLE_LOG_COLORIZE=true

colorized example

Per-property key colors. Every JSON property key gets its own unique ANSI truecolor derived from a hash of the key name. The same key name always appears in the same color across all log lines — userId is always the same hue, orderId is always a different hue, regardless of call site or log level. This makes it easy to scan across many log entries and visually track a specific field.

Automatic background detection. The colorizer detects whether your terminal has a dark or light background and picks foreground colors with appropriate lightness for readability. Dark terminals get bright colors; light terminals get darker tones. Detection checks COLORFGBG, TERM_PROGRAM, WT_SESSION, and VTE_VERSION environment variables, in that order, and defaults to dark-background behavior when no signal is found.

To override detection explicitly:

CONSOLE_LOG_COLORIZE_BACKGROUND=light   # force light-background palette
CONSOLE_LOG_COLORIZE_BACKGROUND=dark    # force dark-background palette

Value colors stay semantic. While key colors are hash-based, value colors remain meaningful: error level is red, warn is yellow, info messages use green, @timestamp values use pink, and so on. These semantics are unaffected by background detection.

Supported Console Methods

Method Default Level
console.error() error
console.warn() warn
console.info() info
console.log() info
console.http() http
console.verbose() verbose
console.debug() debug
console.silly() silly

Configuration

There are three practical ways to configure the logger:

Every configurable setting can now be supplied in either of these ways:

When both are present, precedence is:

  1. Direct LoggerAdaptToConsole({...}) option
  2. envOptions override passed to LoggerAdaptToConsole({...})
  3. Real process.env
  4. Built-in default

This means you can keep environment-specific defaults in deployment config while still overriding individual settings explicitly in code when needed.

Direct Option <-> Env Var Mapping

Direct LoggerAdaptToConsole({...}) option Environment variable Notes
logLevel CONSOLE_LOG_JSON_LOG_LEVEL Env form is a string like warn, error, debug, silly.
debugString CONSOLE_LOG_JSON_DEBUG_STRING Boolean setting.
customOptions CONSOLE_LOG_JSON_CUSTOM_OPTIONS Env form must be a JSON object string.
colorize CONSOLE_LOG_COLORIZE Boolean setting.
noNewLineCharacters CONSOLE_LOG_JSON_NO_NEW_LINE_CHARACTERS Boolean setting.
noNewLineCharactersExceptStack CONSOLE_LOG_JSON_NO_NEW_LINE_CHARACTERS_EXCEPT_STACK Boolean setting.
noTimeStamp CONSOLE_LOG_JSON_NO_TIME_STAMP Boolean setting.
disableAutoParse CONSOLE_LOG_JSON_DISABLE_AUTO_PARSE Boolean setting.
noStackForNonError CONSOLE_LOG_JSON_NO_STACK_FOR_NON_ERROR Boolean setting.
noFileName CONSOLE_LOG_JSON_NO_FILE_NAME Boolean setting.
noPackageName CONSOLE_LOG_JSON_NO_PACKAGE_NAME Boolean setting.
noLoggerDebug CONSOLE_LOG_JSON_NO_LOGGER_DEBUG Boolean setting.
contextKey CONSOLE_LOG_JSON_CONTEXT_KEY Env form is a plain string like context or metadata.
redact CONSOLE_LOG_JSON_REDACT Env form accepts a JSON array/object string or a comma-separated path list.
onLogTimeout CONSOLE_LOG_JSON_ON_LOG_TIMEOUT Env form is a number in milliseconds.
onLog CONSOLE_LOG_JSON_ON_LOG Direct form is a function. Env form is a dotted path on globalThis, like appLoggerHooks.onLog.
transformOutput CONSOLE_LOG_JSON_TRANSFORM_OUTPUT Direct form is a function. Env form is a dotted path on globalThis.

envOptions does not have its own environment-variable equivalent because it is not a logger behavior setting. It is only the programmatic wrapper for supplying env-style values in code.

Output formatting

Variable Default Effect
CONSOLE_LOG_COLORIZE=true false Enable ANSI-colored JSON output. Turn this on for local development – it makes JSON logs much easier to scan in a terminal. Leave it off in production because log ingestion services (LogDNA, DataDog, CloudWatch) don’t render ANSI codes and they add noise to stored logs.
CONSOLE_LOG_COLORIZE_BACKGROUND=dark\|light (auto-detected) Force a specific color palette for colorized output. When not set, the colorizer detects the terminal background from COLORFGBG, TERM_PROGRAM, WT_SESSION, and VTE_VERSION. Set to dark or light to override detection — useful in CI or when auto-detection is wrong for your terminal. Has no effect when CONSOLE_LOG_COLORIZE is not enabled.
CONSOLE_LOG_JSON_NO_NEW_LINE_CHARACTERS=true false Remove all \n characters from the log output, including in stack traces. Turn this on if your log aggregator splits on newlines and you’re seeing stack traces show up as separate log events. The trade-off is that stack traces become harder to read in raw form.
CONSOLE_LOG_JSON_NO_NEW_LINE_CHARACTERS_EXCEPT_STACK=true false A middle ground – removes newlines from the log envelope but keeps them inside stack traces. Useful when your log tool handles multi-line values within a JSON field but splits on newlines between entries.

Controlling metadata fields

These let you reduce log volume and noise. In high-throughput production systems, every byte counts – stripping fields you don’t query on can meaningfully reduce storage costs and improve log search performance.

Variable Default Effect
CONSOLE_LOG_JSON_NO_FILE_NAME=true false Omit @filename. Turn this on if you don’t need source file tracking – for example, in a small service where the package name alone is enough context, or in the browser where it shows <unknown> anyway.
CONSOLE_LOG_JSON_NO_PACKAGE_NAME=true false Omit @packageName. Turn this on in single-package projects where the package name is redundant – every log comes from the same service.
CONSOLE_LOG_JSON_NO_TIME_STAMP=true false Omit @timestamp. Turn this on only if your log transport adds its own timestamp (e.g., CloudWatch automatically timestamps every log entry). Avoids duplicate timestamp fields.
CONSOLE_LOG_JSON_NO_STACK_FOR_NON_ERROR=true false Omit @logCallStack for non-error logs. This is the single most impactful option for reducing log size. Call stacks on every console.log("user signed in") are rarely useful – you typically only need them when debugging errors. Turning this on also improves performance (see below).
CONSOLE_LOG_JSON_NO_LOGGER_DEBUG=true false Omit _loggerDebug. This field is only present when debugString: true is passed to LoggerAdaptToConsole() and is used for debugging the logger itself. Most users will never see this field.

Message handling

Variable Default Effect
CONSOLE_LOG_JSON_DISABLE_AUTO_PARSE=true false Disable automatic JSON parsing of log messages. By default, if you console.log('{"event":"click"}'), the logger detects it’s JSON and extracts it into @autoParsedJson for structured querying. Turn this on if you want JSON strings to stay as plain strings in the message field – for example, if you’re logging raw API responses and don’t want them restructured.

Context nesting

Variable Default Effect
CONSOLE_LOG_JSON_CONTEXT_KEY="context" (empty) When set, all user-provided context object properties are nested under this key instead of being flattened to the top level. This gives your log output a fixed, predictable top-level schema — no “random” properties appearing at the top level that could break DataDog filters, OpenSearch index mappings, or Splunk field extractions. The key name is whatever you set: context, data, metadata, etc. When not set, the default behavior (flatten to top level) is preserved. See the context key example above.

Runtime and hooks

These are the settings that were previously only available as direct LoggerAdaptToConsole(...) options. They now also have environment-variable forms.

Variable Default Effect
CONSOLE_LOG_JSON_LOG_LEVEL=warn info Sets the minimum emitted log level. Supports error, warn, info, http, verbose, debug, silly, plus aliases like err, warning, and information.
CONSOLE_LOG_JSON_DEBUG_STRING=true false Enables _loggerDebug, which captures the raw argument serialization used while building a log line. Mainly useful when debugging the logger itself.
CONSOLE_LOG_JSON_CUSTOM_OPTIONS='{"service":"billing-api","region":"ca-central-1"}' (empty) Adds the same static structured properties to every log entry that customOptions adds in code. Must be a JSON object string.
CONSOLE_LOG_JSON_REDACT='["password","headers.authorization"]' (empty) Supplies the same redaction config as the redact option. Accepts either a JSON array/object string or a simple comma-separated path list.
CONSOLE_LOG_JSON_ON_LOG_TIMEOUT=10000 5000 Sets the timeout, in milliseconds, for the onLog callback before it is abandoned.
CONSOLE_LOG_JSON_ON_LOG=appLoggerHooks.onLog (empty) Resolves onLog from a dotted path on globalThis. This avoids eval while still allowing env-driven hook wiring in advanced setups.
CONSOLE_LOG_JSON_TRANSFORM_OUTPUT=appLoggerHooks.transformOutput (empty) Resolves transformOutput from a dotted path on globalThis. Useful when configuration must be environment-driven but the transform function itself lives in application code.

How env-configured hook references work

CONSOLE_LOG_JSON_ON_LOG and CONSOLE_LOG_JSON_TRANSFORM_OUTPUT do not evaluate JavaScript source code from strings.

This will not work:

CONSOLE_LOG_JSON_ON_LOG="(jsonString, parsedObject) => sendSomewhere(jsonString)"

Instead, put a real function on globalThis and point the env var at it with a dotted path:

globalThis.appLoggerHooks = {
  onLog(jsonString, parsedObject) {
    sendSomewhere(jsonString);
  },
  transformOutput(obj) {
    obj.service = "billing-api";
    return obj;
  }
};

process.env.CONSOLE_LOG_JSON_ON_LOG = "appLoggerHooks.onLog";
process.env.CONSOLE_LOG_JSON_TRANSFORM_OUTPUT = "appLoggerHooks.transformOutput";

LoggerAdaptToConsole();

At startup, the logger walks the dotted path on globalThis and uses the resolved function if it exists. If the path does not resolve to a function, it is ignored safely instead of throwing.

Performance tip

Setting both CONSOLE_LOG_JSON_NO_FILE_NAME=true and CONSOLE_LOG_JSON_NO_STACK_FOR_NON_ERROR=true skips stack trace capture entirely for non-error logs. This eliminates the most expensive operation in the logging pipeline (creating an Error object to capture the stack), reducing per-log overhead to near-zero. Recommended for high-throughput production services where you’re logging hundreds or thousands of events per second and don’t need source file tracking on every info/debug log. Error logs always capture the full stack regardless of these settings.

API Reference

LoggerAdaptToConsole(options?)

Initialize the logger. Call once at application startup.

LoggerAdaptToConsole({
  logLevel?: LOG_LEVEL | string,         // Minimum log level (default: LOG_LEVEL.info)
  debugString?: boolean,                 // Include raw debug string in output (default: false)
  customOptions?: object,                // Static key-value pairs added to every log entry
  colorize?: boolean,                    // Same behavior as CONSOLE_LOG_COLORIZE
  noNewLineCharacters?: boolean,         // Same behavior as CONSOLE_LOG_JSON_NO_NEW_LINE_CHARACTERS
  noNewLineCharactersExceptStack?: boolean, // Same behavior as CONSOLE_LOG_JSON_NO_NEW_LINE_CHARACTERS_EXCEPT_STACK
  noTimeStamp?: boolean,                 // Same behavior as CONSOLE_LOG_JSON_NO_TIME_STAMP
  disableAutoParse?: boolean,            // Same behavior as CONSOLE_LOG_JSON_DISABLE_AUTO_PARSE
  noStackForNonError?: boolean,          // Same behavior as CONSOLE_LOG_JSON_NO_STACK_FOR_NON_ERROR
  noFileName?: boolean,                  // Same behavior as CONSOLE_LOG_JSON_NO_FILE_NAME
  noPackageName?: boolean,               // Same behavior as CONSOLE_LOG_JSON_NO_PACKAGE_NAME
  noLoggerDebug?: boolean,               // Same behavior as CONSOLE_LOG_JSON_NO_LOGGER_DEBUG
  contextKey?: string,                   // Same behavior as CONSOLE_LOG_JSON_CONTEXT_KEY
  envOptions?: Record<string, any>,      // Env-style overrides (same names as env vars, takes precedence over process.env)
  onLog?: ((jsonString: string, parsedObject: any) => void) | string,  // Function or dotted global path
  onLogTimeout?: number,                 // Max time in ms for onLog callback (default: 5000)
  transformOutput?: ((parsedObject: any) => any) | string, // Function or dotted global path
  redact?: string[] | {                  // Redact sensitive structured fields
    paths: string[],
    censor?: any                         // Default: "Redacted"
  } | string                             // JSON string or comma-separated path list when configured indirectly
});

LoggerRestoreConsole()

Restore original console methods. Useful for testing.

GetLogLevel() / SetLogLevel(level)

Read or change the current log level at runtime.

NativeConsoleLog(...args)

Call the original console.log() bypassing JSON formatting. Useful for debugging the logger itself.

ErrorWithContext

import { ErrorWithContext } from "console-log-json";

// Wrap a string
throw new ErrorWithContext("something broke", { userId: 42 });

// Wrap an existing error with additional context
throw new ErrorWithContext(existingError, { retryCount: 3, endpoint: "/api" });

// Nest multiple levels -- full causal chain is preserved
throw new ErrorWithContext(
  new ErrorWithContext(originalError, { innerContext: "value" }),
  { outerContext: "value" }
);

LOG_LEVEL enum

import { LOG_LEVEL } from "console-log-json";

// LOG_LEVEL.error   (priority 0 -- highest)
// LOG_LEVEL.warn    (priority 1)
// LOG_LEVEL.info    (priority 2)
// LOG_LEVEL.http    (priority 3)
// LOG_LEVEL.verbose (priority 4)
// LOG_LEVEL.debug   (priority 5)
// LOG_LEVEL.silly   (priority 6 -- lowest)

Browser Usage

Use the browser guide when you want the same console-to-JSON behavior in a frontend application. The logger works there too, but a few defaults and metadata fields are different from Node.js.

Basic setup

import { LoggerAdaptToConsole } from "console-log-json";
LoggerAdaptToConsole();

// Works the same as Node.js
console.log("button clicked", { component: "Header", action: "menu-toggle" });

Output in the browser DevTools console:

{"level":"info","message":"button clicked","component":"Header","action":"menu-toggle","@filename":"<unknown>","@logCallStack":"at handleClick (src/components/Header.tsx:15:3)","@timestamp":"..."}

The browser field in package.json tells bundlers (webpack, vite, esbuild, etc.) to stub out Node-specific modules automatically. No extra configuration needed.

@filename remains best-effort in bundled browser builds. If your app and console-log-json end up in one output file, stack traces may no longer expose a reliable boundary between library frames and your code, so the logger may emit <unknown> or the bundle path instead of an original source filename.

Configuration in the browser

In the browser, the simplest path is to pass options directly to LoggerAdaptToConsole(...). If you prefer environment-style configuration, envOptions works without touching process.env, and bundler define still works too.

Option 1: Pass options directly (recommended)

import { LoggerAdaptToConsole, LOG_LEVEL } from "console-log-json";

LoggerAdaptToConsole({
  logLevel: LOG_LEVEL.warn,
  customOptions: {
    app: "my-frontend",
    version: "2.1.0"
  },
  noStackForNonError: true,
  noFileName: true,
  noPackageName: true
});

Option 2: Use envOptions parameter (recommended when you want env-style names without process.env)

Pass configuration flags directly to LoggerAdaptToConsole() using the same env var names. This works identically in Node and browser without any environment or bundler setup:

import { LoggerAdaptToConsole, LOG_LEVEL } from "console-log-json";

LoggerAdaptToConsole({
  logLevel: LOG_LEVEL.warn,
  customOptions: {
    app: "my-frontend",
    version: "2.1.0"
  },
  envOptions: {
    CONSOLE_LOG_JSON_NO_STACK_FOR_NON_ERROR: 'true',  // Skip stack capture for non-errors
    CONSOLE_LOG_JSON_NO_FILE_NAME: 'true',             // @filename is <unknown> in browser anyway
    CONSOLE_LOG_JSON_NO_PACKAGE_NAME: 'true'           // No package.json in browser
  }
});

The envOptions parameter accepts the same variable names as the environment variables. Values passed here take precedence over process.env, but direct top-level options still win over both.

Option 3: Set configuration before import (useful for bundlers)

Most bundlers (webpack, vite) support define to replace process.env at build time:

// vite.config.js
export default {
  define: {
    'process.env.CONSOLE_LOG_JSON_DISABLE_AUTO_PARSE': '"true"',
    'process.env.CONSOLE_LOG_JSON_NO_STACK_FOR_NON_ERROR': '"true"',
    'process.env.CONSOLE_LOG_JSON_NO_FILE_NAME': '"true"',
  }
}

// webpack.config.js
const webpack = require('webpack');
module.exports = {
  plugins: [
    new webpack.DefinePlugin({
      'process.env.CONSOLE_LOG_JSON_DISABLE_AUTO_PARSE': '"true"',
      'process.env.CONSOLE_LOG_JSON_NO_STACK_FOR_NON_ERROR': '"true"',
      'process.env.CONSOLE_LOG_JSON_NO_FILE_NAME': '"true"',
    })
  ]
}

Option 4: Set process.env at runtime before initializing

If your bundler doesn’t support define, you can set up a minimal process.env before importing the logger:

// Set up process.env for the browser (before importing console-log-json)
if (typeof process === 'undefined') {
  window.process = { env: {} };
} else if (!process.env) {
  process.env = {};
}

// Now configure
process.env.CONSOLE_LOG_JSON_DISABLE_AUTO_PARSE = 'true';
process.env.CONSOLE_LOG_JSON_NO_STACK_FOR_NON_ERROR = 'true';
process.env.CONSOLE_LOG_JSON_NO_FILE_NAME = 'true';
process.env.CONSOLE_LOG_JSON_CONTEXT_KEY = 'context';

// Then initialize
import { LoggerAdaptToConsole } from "console-log-json";
LoggerAdaptToConsole();

For most frontend applications, you’ll want to reduce noise by disabling features that don’t add value in the browser:

import { LoggerAdaptToConsole } from "console-log-json";

LoggerAdaptToConsole({
  customOptions: { app: "my-frontend" },
  noFileName: true,           // @filename is <unknown> in browser anyway
  noStackForNonError: true,   // Skip stack capture for non-errors (performance)
  noPackageName: true         // No package.json in browser
});

console.log("page loaded", { route: "/dashboard", loadTime: 1.2 });

{"level":"info","message":"page loaded","app":"my-frontend","loadTime":1.2,"route":"/dashboard","@timestamp":"..."}

What works differently in the browser

Feature Node.js Browser
@filename Source file path (e.g. src/index.ts) <unknown> (no filesystem)
@packageName From package.json Empty (no package.json)
.env loading Not performed by the library Not performed by the library
Stack traces V8 format with source maps Browser-native format (source maps work in DevTools)
Output destination process.stdout (JSON string) Browser console.log (visible in DevTools)
Environment variables process.env Set via bundler define or manual process.env setup
Colors (CONSOLE_LOG_COLORIZE) ANSI codes for terminal ANSI codes (visible in Node-based tools, not in browser DevTools)

Advanced Usage

These features work in both Node.js and browser environments. Reach for them when you need to integrate with an existing logging pipeline, reshape output, or enforce structured redaction rules.

Intercepting logs with onLog

The onLog callback lets you intercept every log entry — for example, to send browser logs to a backend, forward to an analytics service, or apply custom transformations. The callback receives the formatted JSON string and the parsed object.

import { LoggerAdaptToConsole } from "console-log-json";

LoggerAdaptToConsole({
  customOptions: { app: "frontend", sessionId: getSessionId() },
  onLog: (jsonString, parsedObject) => {
    // Send to your logging backend
    navigator.sendBeacon('/api/logs', jsonString);

    // Or forward errors to an error tracking service
    if (parsedObject.level === 'error') {
      errorTracker.report(parsedObject);
    }
  }
});

// Logs appear in DevTools as normal AND get sent to your backend
console.log("checkout started", { cartId: "ABC-123", items: 3 });
console.error("payment failed", new Error("card declined"), { cartId: "ABC-123" });

The onLog callback is designed to be safe and non-blocking:

// Customize the timeout (default: 5000ms)
LoggerAdaptToConsole({
  onLog: async (jsonString, parsedObject) => {
    await fetch('/api/logs', { method: 'POST', body: jsonString });
  },
  onLogTimeout: 10000  // 10 seconds
});

This works identically in Node.js and the browser.

Transforming log output with transformOutput

Use transformOutput to modify the log object before it’s written. This lets you rename fields, add properties, remove fields, or completely reshape the output to match your log aggregator’s expected schema.

LoggerAdaptToConsole({
  transformOutput: (obj) => {
    // Rename fields to match DataDog's conventions
    obj.status = obj.level;
    obj.timestamp = obj['@timestamp'];
    delete obj.level;
    delete obj['@timestamp'];

    // Add deployment metadata
    obj.version = '2.1.0';
    obj.environment = 'production';

    return obj;
  }
});

console.log("deploy complete", { service: "payment-api" });

{"status":"info","message":"deploy complete","service":"payment-api","version":"2.1.0","environment":"production","timestamp":"..."}

The transform is crash-safe: if your callback throws an error or returns null/non-object, the original unmodified log output is used as a fallback. Your logs never break, even with a buggy transform.

LoggerAdaptToConsole({
  transformOutput: () => {
    throw new Error('oops');
  }
});

console.log("still works");
// Output: {"level":"info","message":"still works","@timestamp":"..."} (original, unmodified)

transformOutput and onLog can be used together. The transform runs first (modifying what gets written), then onLog receives the transformed result:

LoggerAdaptToConsole({
  transformOutput: (obj) => {
    obj.region = 'us-east-1';
    return obj;
  },
  onLog: (jsonString, parsedObject) => {
    // parsedObject.region === 'us-east-1' — it sees the transformed output
    navigator.sendBeacon('/api/logs', jsonString);
  }
});

Redacting sensitive fields with redact

Use redact to replace sensitive structured values with "Redacted" before the log is written.

LoggerAdaptToConsole({
  redact: ['password', 'headers.authorization', 'payment.card.number']
});

console.log("checkout failed", {
  password: "hunter2",
  headers: { authorization: "Bearer secret-token" },
  payment: { card: { number: "4111111111111111", brand: "visa" } }
});

{"level":"info","message":"checkout failed","password":"Redacted","headers":{"authorization":"Redacted"},"payment":{"card":{"number":"Redacted","brand":"visa"}},"@timestamp":"..."}

For nested arrays and keys with hyphens, use bracket and wildcard syntax:

LoggerAdaptToConsole({
  redact: ['items[*].token', 'headers["x-api-key"]']
});

You can also use the object form to change the replacement value:

LoggerAdaptToConsole({
  redact: {
    paths: ['auth.refreshToken', 'auth.accessToken'],
    censor: 'MASKED'
  }
});

Guidance:

Contributors

Logan.seongjae(Benefit)
Logan.seongjae(Benefit)
💻		 Roberto Sebestyen
Roberto Sebestyen
💻 📖 📆 🛡️ 👀		 Igor Dreher
Igor Dreher
💻		 WesSparla
WesSparla
📖 ⚠️		 Remi Kristelijn
Remi Kristelijn
💻

Changelog

See CHANGELOG.md for release history, breaking changes, and migration guides.

License

MIT