Repolode
Submit
debug-js

debug-js/debug

A tiny JavaScript debugging utility that prints namespaced debug output in Node.js and web browsers, toggled via the DEBUG environment variable.

View on GitHub
Stars
11,458
Forks
998
Open issues
98
Last commit
11 days ago

What is it?

debug is a small logging utility for JavaScript modelled after the debugging technique used in Node.js core. You create a named debug function with a namespace such as 'http' or 'worker:a', and its output is only printed when that namespace is enabled through the DEBUG environment variable. Wildcards and exclusions such as DEBUG=connect:* or DEBUG=*,-connect:* let you narrow output to specific parts of an application.

The library works in both Node.js and web browsers. In Node.js it writes to stderr, supports per-namespace colors, and shows millisecond time differences between calls. In browsers, enabled state is stored in localStorage. It uses printf-style formatters such as %o, %O, %s, %d and %j, and custom formatters can be added by extending debug.formatters.

APIs for extending namespaces, checking whether a namespace is enabled, and enabling or disabling output at runtime are also available.

Key features

  • 01Namespaced debug functions toggled by the DEBUG environment variable.
  • 02Wildcard and exclusion patterns to filter output.
  • 03Works in Node.js and web browsers, with colors where supported.
  • 04Millisecond time diff between calls, or ISO timestamps when output is not a TTY.
  • 05Printf-style formatters with support for custom formatters.
  • 06Runtime enable, disable and extend APIs.

Use cases

  • Adding switchable debug logs to a Node.js library or application without shipping noise by default.
  • Tracing request handling or worker activity in a server process by namespace.
  • Debugging frontend code in the browser by setting localStorage.debug.

Quick start

  1. 1

    Install the package with npm

    npm install debug
  2. 2

    Create a debug instance in your code with a namespace, then run your app with DEBUG enabled (macOS/Linux)

    DEBUG=* node app.js

Things to know

  • Debug output is only shown for namespaces enabled through the DEBUG environment variable or localStorage.debug.
  • Colors in Node.js require the optional supports-color module for full palette support.

In collections

OpenTelemetry & observability platforms

Topics

#javascript#logging#debugging#node#browser#debug-logging#debug#node-js

FAQ

What is debug?
A tiny JavaScript debugging utility that prints namespaced debug output in Node.js and web browsers, toggled via the DEBUG environment variable. debug is a small logging utility for JavaScript modelled after the debugging technique used in Node.js core. You create a named debug function with a namespace such as 'http' or 'worker:a', and its output is only printed when that namespace is enabled through the DEBUG environment variable. Wildcards and exclusions such as DEBUG=connect:* or DEBUG=*,-connect:* let you narrow output to specific parts of an application.
Is debug free to use? What license does it have?
debug is open source under the MIT license. Check the license terms before using it in commercial products.
Is debug still maintained?
Actively maintained. The last commit to debug was on Oct 14, 2026.
What can I use debug for?
Adding switchable debug logs to a Node.js library or application without shipping noise by default. Tracing request handling or worker activity in a server process by namespace. Debugging frontend code in the browser by setting localStorage.debug.
How do I install debug?
Install the package with npm: npm install debug Create a debug instance in your code with a namespace, then run your app with DEBUG enabled (macOS/Linux): DEBUG=* node app.js
Where can I get debug?
The source code and installation instructions are on GitHub: https://github.com/debug-js/debug

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects