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.08 kB minified + gzipped (plain)
1.52 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
Runtimes
obug automatically selects ANSI output for Node.js/Bun/Deno, plain console output for React Native/Expo and Cloudflare Workers/Vercel Edge/Fastly Compute, and CSS console colors for browsers.
To choose explicitly, import obug/ansi, obug/plain, or obug/browser.
JSR defaults to the browser implementation without automatic selection. Use jsr:@sxzz/obug/ansi for terminals or jsr:@sxzz/obug/plain for plain output.
Usage
import { createDebug, disable, enable, enabled, namespaces } from 'obug'// Get the currently enabled namespacesconsole.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 debuggerconst 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: