obug

obug

A lightweight JavaScript debugging utility, forked from debug, featuring TypeScript and ESM support.

[!NOTE] obug v1 retains most of the compatibility with debug, but drops support for older browsers and Node.js, making it a drop-in replacement.

obug v2 refactors some API imports and usage for better support of ESM and TypeScript, easier customization, and an even smaller package size.

Key Differences from debug

• ✨ Minimal footprint
  • 1.50 kB minified + gzipped (plain)
  • 1.48 kB minified + gzipped (browser)
  • 1.73 kB minified + gzipped (ansi)
• 📦 Zero dependencies
• 📝 Full TypeScript support
• 🚀 Native ESM compatibility
• 🌐 Optimized for modern runtimes
  • ES2015+ browsers
  • Modern Node.js versions
• 🎨 Customizable formatting

Installation

npm install obug

Runtime entries

The default npm entry selects an implementation through conditional exports:

Runtime	Entry	Output
Node.js, Bun, Deno	obug	ANSI output to stderr
React Native / Expo	obug	React Native console output
Cloudflare Workers, Vercel Edge, Fastly Compute	obug	Plain console output
Browsers	obug	Browser-style output to the console

Use an explicit entry when a bundler does not provide the appropriate export condition:

import { createDebug } from 'obug/ansi' // terminal / ANSI output
import { createDebug } from 'obug/browser' // browser-style console output
import { createDebug } from 'obug/plain' // plain console output

JSR does not provide conditional exports. Its default entry remains the ANSI implementation, and the existing node subpath is retained as an alias. Use explicit subpaths for browser or plain console output:

import { createDebug } from 'jsr:@sxzz/obug' // terminal / ANSI output
import { createDebug } from 'jsr:@sxzz/obug/browser' // browser-style console output
import { createDebug } from 'jsr:@sxzz/obug/plain' // plain console output

Usage

import { createDebug, disable, enable, enabled, namespaces } from 'obug'

// Get the currently enabled namespaces
console.log(namespaces())

const debug = createDebug('my-namespace', {
  // All options are optional

  useColors: true, // false, true, undefined for auto-detect
  color: 2, // custom color
  // custom formatArgs
  formatArgs(args) {},
  formatters: {},
  // Node.js only
  inspectOpts: {},

  // custom log
  log: console.log,
})

debug('This is a debug message')
console.log(
  debug.namespace, // 'my-namespace'
  debug.enabled, // Check if enabled
  debug.useColors, // true
  debug.color, // 2
  debug.formatArgs, // custom formatArgs
  debug.formatters, // {}
  debug.inspectOpts, // {}
  debug.log, // implemented log function
)

// Create a sub-namespace, and it will inherit options from the parent debugger
const sub = debug.extend('sub-namespace')
sub('This is a sub-namespace debug message')
console.log(sub.namespace) // 'my-namespace:sub-namespace'

How to use

Enabling debug output

obug picks up enabled namespaces from the DEBUG environment variable in Node.js, or from localStorage.debug in browsers.

In Node.js:

DEBUG=app:* node app.js

On Windows (CMD):

set DEBUG=app:* & node app.js

On Windows (PowerShell):

$env:DEBUG='app:*'; node app.js

In the browser, set the value in DevTools and refresh the page:

localStorage.debug = 'app:*'

Wildcards and exclusion

The * character is a wildcard. Suppose your library has debuggers named connect:bodyParser, connect:compress, and connect:session — instead of listing each one, use DEBUG=connect:*. Use DEBUG=* to enable everything.

Exclude namespaces by prefixing them with -:

DEBUG=*,-connect:* node app.js

Namespace conventions

If you're using obug in a library, prefix your namespaces with the library name and use : to separate features (e.g. connect:bodyParser). This lets users opt into the parts they care about without guessing names.

Extending a namespace

Use .extend() to create a sub-namespace that inherits options from its parent:

const log = createDebug('auth')
const logSign = log.extend('sign') // 'auth:sign'
const logLogin = log.extend('login') // 'auth:login'

log('hello') // auth hello
logSign('hello') // auth:sign hello
logLogin('hello') // auth:login hello

Formatters

obug uses printf-style formatting. Built-in formatters:

Formatter	Representation
%O	Pretty-print an Object on multiple lines.
%o	Pretty-print an Object all on a single line.
%%	Single percent sign. Does not consume an argument.

Other format specifiers supported by Node's util.format (%s, %d, %j, …) and the browser console pass through to the underlying logger.

Custom formatters

Register custom formatters via the formatters option. For example, to render a Buffer as hex with %h:

const debug = createDebug('foo', {
  formatters: {
    h: (v) => v.toString('hex'),
  },
})

debug('this is hex: %h', Buffer.from('hello world'))
//   foo this is hex: 68656c6c6f20776f726c64 +0ms

Dynamic enable / disable

You can toggle namespaces at runtime:

import { disable, enable, enabled, namespaces } from 'obug'

enable('app:*')
console.log(enabled('app:server')) // true

const previous = disable()
console.log(enabled('app:server')) // false

// Restore later
enable(previous)

namespaces() returns the string of currently enabled namespaces. Note that calling enable() overrides the value initially read from DEBUG.

Checking whether a debugger is enabled

Guard expensive work behind the enabled property:

const debug = createDebug('http')

if (debug.enabled) {
  // expensive computation only when enabled
}

You can also force the state by assigning to debug.enabled directly.

Custom output

By default, obug writes to stderr in Node.js and to the console in browsers. Override the log option to redirect output per-namespace:

const log = createDebug('app:log', {
  log: console.log,
})

const error = createDebug('app:error') // still goes to stderr

Environment variables (Node.js)

Name	Purpose
DEBUG	Enables/disables specific debugging namespaces.
DEBUG_HIDE_DATE	Hide date from debug output (non-TTY).
DEBUG_COLORS	Whether to use colors in the debug output.
DEBUG_DEPTH	Object inspection depth.
DEBUG_SHOW_HIDDEN	Shows hidden properties on inspected objects.

Variables prefixed with DEBUG_ are converted to camelCase keys on the options object passed to Node's util.inspect() for the %o / %O formatters.

Original Authors

As obug is a fork of debug with significant modifications, we would like to acknowledge the original authors:

• TJ Holowaychuk
• Nathan Rajlich
• Andrew Rhyne
• Josh Junon

Sponsors

License

MIT License © 2025-PRESENT Kevin Deng

The MIT License Copyright (c) 2014-2017 TJ Holowaychuk <[e-mail]>

The MIT License Copyright (c) 2018-2021 Josh Junon