debug

debug is a minimalist JavaScript debugging utility modelled after Node.js core’s own internal debugging technique. It lets you wrap conditional log output in named debug instances that stay completely silent in production unless explicitly enabled, so you can sprinkle diagnostic statements throughout a codebase without paying a runtime cost or cluttering normal output.

Output is toggled entirely through the DEBUG environment variable (or localStorage.debug in the browser), with wildcard and exclusion patterns for selecting exactly which namespaces to surface. Each namespace gets an automatic color, printf-style formatters, and millisecond timing diffs between calls, making it one of the most widely depended-on packages in the npm ecosystem.

What You Get

• A tiny factory API: require('debug')('namespace') returns a ready-to-use logging function
• Runtime enable/disable controlled by the DEBUG env var (or localStorage.debug in browsers) with wildcard and exclusion patterns
• Automatic per-namespace colors and millisecond timing diffs between successive calls
• printf-style formatters (%o, %O, %s, %d, %j) plus support for registering custom formatters
• Isomorphic builds for both Node.js and the browser from a single package

Common Use Cases

• Instrumenting a library so downstream consumers can toggle its internal logging without code changes
• Adding low-overhead, namespaced diagnostics to an application that stay quiet in production
• Selectively enabling logs from specific subsystems (e.g. DEBUG=app:db,app:http) while excluding noisy ones

Under The Hood

Architecture — The package is deliberately small and factored around a shared core: src/index.js sniffs the runtime (checking process.type, process.browser, and process.__nwjs) and delegates to either src/node.js or src/browser.js, each of which supplies environment-specific concerns (color detection, output stream, env parsing) into the common setup(env) factory in src/common.js. That factory builds the createDebug function, whose per-namespace debug closure tracks previous timestamps, computes millisecond diffs, applies formatters, and short-circuits immediately when disabled.

Tech Stack — Pure JavaScript targeting node >=6, with a single runtime dependency (ms for humanizing time diffs) and an optional supports-color peer dependency for richer Node color output. Browser bundles are produced with browserify; tests run on mocha with sinon, and karma drives the browser test suite. Linting is handled by xo.

Code Quality — The codebase is compact and well-commented, with a clear separation between shared logic and platform adapters. Tests exist (test.js plus test.node.js) covering enable/disable semantics, formatting, and namespace matching, run through mocha and karma. The narrow API surface and long production history across hundreds of millions of weekly downloads make it battle-tested.

API Design — The public API is exceptionally ergonomic: require('debug')('namespace') returns a callable logger, and everything else (wildcards, exclusions, .extend(), .enable()/.disable(), custom formatters, per-instance log overrides) layers on without ceremony. Zero configuration is required to get started, and runtime control via the DEBUG env var means instrumentation needs no code changes to toggle.