{"id":10722,"library":"debug","title":"Debug Logger","description":"The `debug` package is a lightweight and highly popular debugging utility designed for both Node.js and web browser environments. Currently stable at version `4.4.3`, it maintains a regular release cadence with frequent patch and minor updates addressing bug fixes and minor enhancements. Its core functionality revolves around providing a simple, namespace-based logging mechanism that allows developers to selectively enable or disable debug output for different parts of an application using the `DEBUG` environment variable (or `localStorage` in browsers). Key differentiators include its minimal footprint, automatic colorized output in supported terminals and browser developer tools, and the useful millisecond difference displayed between consecutive log calls, aiding in performance analysis. The project recently migrated its repository from `visionmedia/debug` to `debug-js/debug`. It is crucial to note that version `4.4.2` was compromised and users should upgrade immediately to `4.4.3` or later to avoid potential security risks.","status":"active","version":"4.4.3","language":"javascript","source_language":"en","source_url":"git://github.com/debug-js/debug","tags":["javascript","debug","log","debugger"],"install":[{"cmd":"npm install debug","lang":"bash","label":"npm"},{"cmd":"yarn add debug","lang":"bash","label":"yarn"},{"cmd":"pnpm add debug","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for parsing duration strings in some internal operations.","package":"ms","optional":false},{"reason":"Recommended for full color support in Node.js environments when stderr is a TTY.","package":"supports-color","optional":true}],"imports":[{"note":"The primary export is a default function. Named import is incorrect for the main function.","wrong":"import { debug } from 'debug';","symbol":"debug","correct":"import debug from 'debug';"},{"note":"In CommonJS, `require('debug')` returns a function that must be called with a namespace to create a debugger instance.","wrong":"const debug = require('debug');\ndebug('my-namespace', 'hello');","symbol":"debug factory","correct":"const createDebug = require('debug');\nconst debug = createDebug('my-namespace');"},{"note":"Since `4.4.0`, `.enable()` no longer supports regex input directly; use glob patterns (e.g., `*`, `-`) instead.","wrong":"debug.enable(/my-app:.*/);","symbol":"debug.enable","correct":"import debug from 'debug';\ndebug.enable('my-app:*');"}],"quickstart":{"code":"import createDebug from 'debug';\n\nconst appDebug = createDebug('my-app:main');\nconst workerADebug = createDebug('my-app:worker:a');\nconst workerBDebug = createDebug('my-app:worker:b');\n\n// --- app.ts ---\nappDebug('Booting up application.');\n\n// Simulate an HTTP server setup\nsetTimeout(() => {\n  appDebug('Server listening on port 3000');\n  // Simulate a request\n  appDebug('GET /users');\n}, 100);\n\n// --- worker.ts ---\nfunction workA() {\n  workerADebug('Doing lots of uninteresting work...');\n  setTimeout(workA, Math.random() * 500);\n}\n\nfunction workB() {\n  workerBDebug('Doing some specific work...');\n  setTimeout(workB, Math.random() * 1000);\n}\n\nworkA();\nworkB();\n\n// To run this example:\n// 1. Save as `example.ts`\n// 2. Transpile (e.g., `tsc example.ts`)\n// 3. Run with `DEBUG='my-app:*' node example.js`\n//    On Windows PowerShell: `$env:DEBUG='my-app:*'; node example.js`","lang":"typescript","description":"Demonstrates creating multiple debugger instances with different namespaces and enabling them via the `DEBUG` environment variable."},"warnings":[{"fix":"Upgrade to `debug@4.4.3` or a later stable version. Review your `package-lock.json` or `yarn.lock` to ensure `4.4.2` is not being pulled in by transitive dependencies.","message":"Version `4.4.2` was compromised and contains malicious code. It is critical to avoid this version and upgrade immediately.","severity":"breaking","affected_versions":"4.4.2"},{"fix":"Migrate your `.enable()` calls from regexes to glob patterns (e.g., `*`, `-`). For instance, `debug.enable('foo:*|bar:*')` instead of `debug.enable(/(foo|bar):.*/)`. Regex functionality will not be re-added.","message":"The `.enable()` API no longer supports regular expressions as input. Providing regex patterns will not work as expected and may lead to inefficient warnings.","severity":"breaking","affected_versions":">=4.4.0"},{"fix":"Install `supports-color` as a dependency: `npm install supports-color`.","message":"For optimal colorized output in Node.js, the optional `supports-color` package should be installed alongside `debug`. Without it, `debug` will only use a limited set of basic colors.","severity":"gotcha","affected_versions":">=2.x"},{"fix":"On CMD: `set DEBUG=* & node app.js`. On PowerShell: `$env:DEBUG='*'; node app.js`. On Linux/macOS: `DEBUG='*' node app.js`.","message":"Setting the `DEBUG` environment variable differs across Windows command prompts (CMD vs PowerShell) and Linux/macOS shells. Incorrect syntax will result in debug messages not appearing.","severity":"gotcha","affected_versions":">=2.x"},{"fix":"Upgrade `debug` to `4.3.6` or later to benefit from internal fixes. Modernize your own codebase to use `String.prototype.substring()` or `slice()` instead of `substr()`, and named capture groups for regexes.","message":"Older versions of `debug` used `String.prototype.substr()` and `RegExp.$1`, which are deprecated APIs. While `debug` has updated internally, ensure your own code avoids these where possible.","severity":"deprecated","affected_versions":"<4.3.6"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the `DEBUG` environment variable is correctly set before running your application. For example, `DEBUG='my-app:*' node app.js` (Linux/macOS), `set DEBUG=my-app:* & node app.js` (Windows CMD), or `$env:DEBUG='my-app:*'; node app.js` (Windows PowerShell).","cause":"The `DEBUG` environment variable is not set or is set incorrectly for your shell.","error":"Debug messages are not appearing in the console."},{"fix":"Always call `require('debug')` or `import debug from 'debug'` with a namespace string. Correct: `const myDebug = require('debug')('my-namespace'); myDebug('hello');`","cause":"You are trying to call the `debug` module directly without first creating a debugger instance by providing a namespace string.","error":"TypeError: debug is not a function"},{"fix":"Install `supports-color` (`npm install supports-color`) and ensure your Node.js application is running in an environment where `process.stderr` is a TTY (e.g., directly in a terminal, not piped to a file).","cause":"The `supports-color` package is not installed, or your terminal emulator does not support colors (is not a TTY).","error":"Colors are not showing in debug output in Node.js."}],"ecosystem":"npm"}