Open-Source Observability · debug-js

debug

debug is a lightweight JavaScript logging utility that enables selective, namespaced debug output in Node.js and browsers via environment variables. Developers toggle debug namespaces on/off without code changes, making it ideal for development-time diagnostics.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/debug-js/debug

11.4k

GitHub stars

984

Forks

JavaScript

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	debug-js/debug
Owner	debug-js
Primary language	JavaScript
License	MIT — OSI-approved
Stars	11.4k
Forks	984
Open issues	87
Latest release	4.4.3 (2025-09-13)
Last updated	2026-04-01
Source	https://github.com/debug-js/debug

What debug is

A minimal Printf-style formatter wrapping console.error, supporting namespace filtering, colored TTY output, millisecond deltas, and localStorage persistence in browsers. Works in Node.js and modern web browsers with built-in formatters (%s, %d, %o, %O, %j) and custom formatter extension.

Quickstart

Get the debug source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/debug-js/debug.git2cd debug3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Development-time diagnostics across microservices

Enable granular logging per component (e.g., DEBUG=auth:*,db:* node app.js) without production noise or code rewrites.

Browser DevTools integration

Persist debug state via localStorage; output styled in browser console with namespace colors for visual parsing.

Library instrumentation

Embedded in popular npm packages (Express, Mongoose, Socket.io) allowing end-users to toggle library internals via DEBUG env var.

Implementation considerations

Namespace conventions should follow 'library:feature' pattern to avoid collisions and enable wildcard filtering.
Install optional 'supports-color' module alongside debug to enable full TTY color palette; otherwise limited to basic colors.
DEBUG environment variable filtering supports wildcards (*) and exclusion (-); document expected namespaces for teams.
In non-TTY contexts (CI/logs), output defaults to ISO timestamps; consider DEBUG_COLORS and DEBUG_DEPTH tuning.
Custom formatters extend debug.formatters; ensure they do not throw or block the event loop in high-frequency logging.

When to avoid it — and what to weigh

Production logging required — Not designed for structured logging, persistence, or alerting. Use Winston, Pino, or Bunyan for production observability.
High-volume log ingestion needed — No built-in log aggregation, filtering, or sampling. Stderr-based output unsuitable for log shippers at scale.
Security-sensitive contexts — Environment variable control means debug output could leak secrets if DEBUG env var is misconfigured or overridden in production.
Custom serialization or context tracking — No async context propagation, request tracing, or metadata binding. Primitives only (namespace + message + formatters).

License & commercial use

MIT License. Permissive OSI license permitting commercial use, modification, and distribution with attribution. No warranty.

MIT license explicitly permits commercial use, including proprietary software. No restrictions on closed-source or SaaS deployments. Requires retention of license notice and copyright.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

No inherent security vulnerabilities documented in README. Risk: DEBUG env var controls output—if set to '*' in production, may expose sensitive data (secrets, API keys) in logs. Ensure env var isolation between dev and prod. No validation/sanitization of format strings; malformed %o on circular refs returns '[Circular]'—safe but verify in security-critical contexts.

Alternatives to consider

Winston

Full-featured logging framework with transport layers, structured logging, and production-grade log aggregation. Heavier footprint; better for enterprise/SaaS.

Pino

High-performance JSON logging for Node.js with async context, child loggers, and log streaming. Stricter structure; less suitable for ad-hoc debugging.

console.log with conditional checks

Zero dependencies; requires manual if(DEBUG) guards in code. No filtering, no formatting, no localStorage in browsers. Suitable only for trivial cases.

Software development agency

Build on debug with DEV.co software developers

Integrate debug into your Node.js or browser app in minutes. Or contact our team to discuss structured logging for production systems.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

loglevel opentelemetry-js logtape

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Observability Application Development API Development DevOps Talk to DEV.co

debug FAQ

Can I use debug in production?

Not recommended. debug is designed for development diagnostics. For production logging, use Winston, Pino, or Bunyan. If you must use debug, never set DEBUG=* in production; it may leak secrets.

Does debug support log levels (info, warn, error)?

No. debug is a single-level tool. All output goes to stderr. Route to different streams per namespace or use a structured logger if levels are needed.

How do I use debug in the browser?

Include debug via npm or browserify-as-a-service, then set localStorage.debug = 'namespace:*' in the console or code. Output appears in DevTools console with colors (WebKit, Firefox 31+).

Can I extend debug formatters?

Yes. Modify debug.formatters object with custom functions, e.g., debug.formatters.h = (v) => v.toString('hex'). Then use %h in debug() calls.

Custom software development services

From first prototype to production, DEV.co delivers software development services around tools like debug. Our software development agency staffs experienced software developers and web developers for custom software development, web development, integrations, and ongoing support across open-source observability and beyond.

Ready to streamline your development debugging?

Integrate debug into your Node.js or browser app in minutes. Or contact our team to discuss structured logging for production systems.

Talk to DEV.co Schedule a Consultation