Debug Logger

Common errors

• Debug messages are not appearing in the console.

  cause The `DEBUG` environment variable is not set or is set incorrectly for your shell.
  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).

• TypeError: debug is not a function

  cause You are trying to call the `debug` module directly without first creating a debugger instance by providing a namespace string.
  fix Always call `require('debug')` or `import debug from 'debug'` with a namespace string. Correct: `const myDebug = require('debug')('my-namespace'); myDebug('hello');`

• Colors are not showing in debug output in Node.js.

  cause The `supports-color` package is not installed, or your terminal emulator does not support colors (is not a TTY).
  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).

Warnings

• breaking Version `4.4.2` was compromised and contains malicious code. It is critical to avoid this version and upgrade immediately.
  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.
• breaking The `.enable()` API no longer supports regular expressions as input. Providing regex patterns will not work as expected and may lead to inefficient warnings.
  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.
• gotcha 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.
  Fix: Install `supports-color` as a dependency: `npm install supports-color`.
• gotcha 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.
  Fix: On CMD: `set DEBUG=* & node app.js`. On PowerShell: `$env:DEBUG='*'; node app.js`. On Linux/macOS: `DEBUG='*' node app.js`.
• deprecated 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.
  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.

Install

• npm install debug npm
• yarn add debug yarn
• pnpm add debug pnpm

Imports

• debug
  wrong:

  import { debug } from 'debug';

  correct:

  import debug from 'debug';

  The primary export is a default function. Named import is incorrect for the main function.
• debug factory
  wrong:

  const debug = require('debug');
  debug('my-namespace', 'hello');

  correct:

  const createDebug = require('debug');
  const debug = createDebug('my-namespace');

  In CommonJS, `require('debug')` returns a function that must be called with a namespace to create a debugger instance.
• debug.enable
  wrong:

  debug.enable(/my-app:.*/);

  correct:

  import debug from 'debug';
  debug.enable('my-app:*');

  Since `4.4.0`, `.enable()` no longer supports regex input directly; use glob patterns (e.g., `*`, `-`) instead.

Quickstart

Demonstrates creating multiple debugger instances with different namespaces and enabling them via the `DEBUG` environment variable.

import createDebug from 'debug';

const appDebug = createDebug('my-app:main');
const workerADebug = createDebug('my-app:worker:a');
const workerBDebug = createDebug('my-app:worker:b');

// --- app.ts ---
appDebug('Booting up application.');

// Simulate an HTTP server setup
setTimeout(() => {
  appDebug('Server listening on port 3000');
  // Simulate a request
  appDebug('GET /users');
}, 100);

// --- worker.ts ---
function workA() {
  workerADebug('Doing lots of uninteresting work...');
  setTimeout(workA, Math.random() * 500);
}

function workB() {
  workerBDebug('Doing some specific work...');
  setTimeout(workB, Math.random() * 1000);
}

workA();
workB();

// To run this example:
// 1. Save as `example.ts`
// 2. Transpile (e.g., `tsc example.ts`)
// 3. Run with `DEBUG='my-app:*' node example.js`
//    On Windows PowerShell: `$env:DEBUG='my-app:*'; node example.js`