{"id":12747,"library":"obug","title":"obug Lightweight Debugging Utility","description":"obug is a lightweight JavaScript debugging utility, forked from the popular `debug` package, specifically engineered for modern JavaScript environments. It offers comprehensive TypeScript support and native ES Module (ESM) compatibility, making it suitable for contemporary Node.js applications and browser environments (ES2015+). The current stable version is 2.1.1, with recent updates focusing on performance enhancements and customizable features. Unlike its predecessor `debug`, obug prioritizes a minimal footprint (7.7 kB package size, 1.4 KB minified + gzipped for browsers) and zero external dependencies. Key differentiators include full TypeScript type definitions, native ESM support from the ground up, and an API optimized for modern runtimes. Version 2 introduced a significant rewrite, refactoring API imports and usage for improved modularity, customization, and further reduced package size compared to v1, which aimed for `debug` compatibility but dropped older runtime support.","status":"active","version":"2.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/sxzz/obug","tags":["javascript","typescript"],"install":[{"cmd":"npm install obug","lang":"bash","label":"npm"},{"cmd":"yarn add obug","lang":"bash","label":"yarn"},{"cmd":"pnpm add obug","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"v2 refactored API imports, use named exports for ESM.","wrong":"const createDebug = require('obug').createDebug","symbol":"createDebug","correct":"import { createDebug } from 'obug'"},{"note":"v2 refactored API imports, use named exports for ESM.","wrong":"const disable = require('obug').disable","symbol":"disable","correct":"import { disable } from 'obug'"},{"note":"v2 refactored API imports, use named exports for ESM.","wrong":"const namespaces = require('obug').namespaces","symbol":"namespaces","correct":"import { namespaces } from 'obug'"}],"quickstart":{"code":"import { createDebug, disable, enable, enabled, namespaces } from 'obug';\n\n// Enable debug messages for 'my-namespace' and its sub-namespaces\nenable('my-namespace*');\n\n// Get the currently enabled namespaces\nconsole.log('Enabled namespaces:', namespaces());\n\nconst debug = createDebug('my-namespace', {\n  // All options are optional\n  useColors: true, // false, true, undefined for auto-detect\n  color: 2, // custom color (e.g., ANSI color code)\n  // custom formatArgs (Node.js only)\n  formatArgs(args) {\n    // Example: prepend a timestamp\n    args[0] = `[${new Date().toISOString()}] ${args[0]}`;\n  },\n  formatters: {}, // custom formatters (like debug.formatters)\n  // Node.js only options\n  inspectOpts: { depth: 4 },\n  // custom log function\n  log: console.log,\n});\n\n// This message will be logged because 'my-namespace' is enabled\ndebug('This is a debug message for %s', 'my-component');\nconsole.log(\n  'Namespace:', debug.namespace, // 'my-namespace'\n  'Enabled:', debug.enabled,     // true\n  'Using colors:', debug.useColors, // true\n);\n\n// Create a sub-namespace, inheriting options from the parent\nconst sub = debug.extend('sub-namespace');\nsub('This is a sub-namespace debug message with an object: %o', { id: 123, status: 'active' });\nconsole.log('Sub-namespace:', sub.namespace); // 'my-namespace:sub-namespace'\n\n// Example of disabling debug messages\ndisable('my-namespace*');\nconsole.log('Enabled after disable:', enabled('my-namespace')); // Should be false or empty\n\nconst debug2 = createDebug('another-namespace');\ndebug2('This message will NOT appear because its namespace is not enabled.');","lang":"typescript","description":"Demonstrates `obug` installation, creating debuggers, enabling/disabling namespaces, and using sub-namespaces."},"warnings":[{"fix":"Update all import statements to use named exports (e.g., `import { createDebug } from 'obug'`) instead of relying on a default export or a CommonJS-style `require('obug')` that returns a function.","message":"obug v2 introduced a significant rewrite that refactors API imports and usage compared to v1. Direct replacements for `debug`'s default export might not work without modification.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your project's target environment supports ES2015+ features (e.g., modern browsers, Node.js 14+). If targeting older runtimes, consider using the original `debug` package or transpiling your code.","message":"obug drops support for older browsers and Node.js versions compared to the original `debug` package, specifically targeting ES2015+ environments.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Prefer `import ... from 'obug'` syntax. If using CommonJS, ensure your build setup correctly handles ESM imports or configure Node.js with `--experimental-loader esm` (though named imports are still the preferred way).","message":"obug is designed with native ES Module (ESM) compatibility in mind. Using CommonJS `require()` in an ESM context or a mixed environment without proper configuration can lead to import issues.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use the named export `createDebug` explicitly: `import { createDebug } from 'obug'; const debug = createDebug('my-namespace');`","cause":"Attempting to call the top-level `obug` module as a function (similar to `require('debug')('namespace')`) in an ESM context, or incorrectly importing the default export.","error":"TypeError: obug is not a function"},{"fix":"Ensure you are using `import { createDebug } from 'obug';` for ESM, and verify that your environment is properly configured for ESM. If strictly in CJS, you may need a bundler to resolve the ESM module correctly.","cause":"Incorrectly trying to destructure `createDebug` from a CommonJS `require('obug')` that doesn't expose it this way, or a typo in the named import.","error":"TypeError: Cannot read properties of undefined (reading 'createDebug')"},{"fix":"Convert your module to use ES Module syntax (`import`/`export`). `obug` is built for ESM, and mixing CJS patterns can lead to errors.","cause":"Attempting to use CommonJS-specific globals (`exports`, `module.exports`, `require`) within an ES Module file (`.mjs` or `type: \"module\"` in `package.json`).","error":"ReferenceError: exports is not defined in ES module scope"}],"ecosystem":"npm"}