wiretap

Extremely tiny debug logging utility for all JavaScript runtimes.

Inspired by debug, but very small and portable.

Installation

# npm
npm install w

# yarn
yarn add w

# pnpm
pnpm add w

# bun
bun add w

# deno
deno add jsr:@mkr/wiretap

Quick Start

import { w } from "w";

const log = w("app:main");
log("Creating new user", { email: req.body.email });

const log = w("app:auth");
log("User authentication failed", { email: req.body.email });

If you're a library author, we recommend using your library's name as part of your namespace.

Usage

All debug logs are disabled by default, and can be enabled by setting the DEBUG environment variable.

> DEBUG=app:main node index.js
app:main Creating new user { email: 'a@test.com' }

To enable all logs at any level, use *. Naturally DEBUG=* will enable all logs at all levels.

> DEBUG=app:* node index.js
app:main Creating new user { email: 'a@test.com' }
app:auth User authentication failed { email: 'b@test.com' }

Multiple namespaces can be specified by separating them with commas:

> DEBUG=app:main,app:auth node index.js
app:main Creating new user { email: 'a@test.com' }
app:auth User authentication failed { email: 'b@test.com' }

To disable a specific level, prefix the spec with a -:

# all "app" enabled except "app:auth"
> DEBUG=app:*,-app:auth node index.js
app:main Creating new user { email: 'a@test.com' }

🔔 The most specific rule always wins.

Example: app:*,-app:auth,app:auth:warning

Explanation:

• all namespaces under app are enabled
• but app:auth is disabled
• but app:auth:warning is enabled

# notice that we didn't get app:auth, but we did get app:auth:warning
> DEBUG=app:*,-app:auth,app:auth:warning node index.js
app:main Creating new user { email: 'a@test.com' }
app:auth:warning User authentication failed { email: 'b@test.com' }

Panic

Each logger instance includes a panic method that can be used for critical errors that should halt execution completely:

const log = w("app:critical");
log.panic("Fatal error occurred", { error }); // This will never return

By default, panic will:

1. Log the error message to stderr
2. Print a stack trace
3. Trigger a debugger break
4. Attempt to exit the process or show an alert (in browsers)
5. Fallback to infinite loop

You can configure panic to throw an error instead by setting the W_PANIC_THROWS=1 environment variable.

Programmatic Control

An individual logger instance can also be enabled or disabled programmatically:

const log = w("app:feature");

// Enable this logger regardless of DEBUG environment
log.enabled = true;

// Disable this logger regardless of DEBUG environment
log.enabled = false;

By default, wiretap will log to stderr. You can customise the logger function used:

const log = w("app:custom");
// Replace the default logger with your own
log.logger = console.log.bind(console); // or
log.logger = (...args) => console.log("[CUSTOM]", ...args);

Colour Configuration

By default, wiretap will use colours in environments that support it. wiretap will read the following environment variables (in order of precedence):

• FORCE_COLOR: Force enable coloured output
• NO_COLOR: Disable coloured output
• CI: Disable coloured output in CI environments

Supported Environments:

• Node.js
• Bun
• Deno
• Cloudflare Workers
• Browsers (by default, you may need to turn on the "debug", "verbose", or similar setting in the console to see the logs in your browser to see debug logs)