debug-frontend

Features

• Lightweight and Zero-Dependency: Built with pure JavaScript, debug-frontend has no external dependencies. This ensures a minimal bundle size and eliminates concerns about third-party vulnerabilities, making it a secure and efficient choice for your projects.
• Namespace-Based Logging: Organize your logs by feature, component, or module. Enable only what you need, when you need it.
• Automatic Console Overriding: Seamlessly integrates with your existing console.log, console.info, etc., automatically routing them through debug-frontend's namespacing system.
• Interactive Runtime UI: A built-in, accessible UI allows you to enable/disable debug namespaces on the fly directly in your browser, without touching code or localStorage manually.
• Color-Coded Output: Logs are automatically colored by namespace, making it easier to distinguish different types of output at a glance.
• UMD and ES Module builds: Use it in any project, modern or legacy.

Installation

npm install debug-frontend

Usage

ES Module (Recommended)

import debug from 'debug-frontend';

const log = debug('app:main');
const dataLog = debug('app:data');

log('Application started.');
dataLog('Fetched user data:', { id: 1, name: 'Alice' });

UMD (for older browsers or non-module setups)

Include the script in your HTML:

<script src="node_modules/debug-frontend/dist/index.js"></script>

Then you can use the debug function globally:

const log = debug('app:log');
log('This is a log message');

Controlling Logs

There are two primary ways to control log visibility:

1. Using localStorage: Open your browser's developer console and set the localStorage.debug item:

   localStorage.debug = 'app:*'; // Enable all 'app' related logs
   localStorage.debug = 'app:main,-app:data'; // Enable app:main, disable app:data
   

2. Using the Runtime UI: Press Shift + D + Enter in your browser. A modal will appear, allowing you to visually select and toggle namespaces. This is incredibly powerful for live debugging sessions.

   You can also programmatically open this UI by calling console.configure().

Advanced Usage

Overriding the Native Console

By default, debug-frontend will override the native console methods (log, info, warn, error, etc.) with its own namespaced versions. This means that all of your existing console.log() calls will automatically become part of the debug-frontend system, under the app namespace (e.g., app:log, app:info).

This is useful for quickly adding debug capabilities to an existing project without having to change all of your logging statements.

Creating Namespaced Consoles with replicate()

For more granular control, especially in larger applications or component-based libraries, you can use the console.replicate() method to create a new console object with its own namespace.

// Create a new console object for your component
const myComponentConsole = console.replicate('MyComponent');

// Now you can use the new console object to log messages
myComponentConsole.log('This is a log message from MyComponent');
myComponentConsole.warn('This is a warning from MyComponent');

// These logs will have the namespaces 'app:MyComponent:log' and 'app:MyComponent:warn' respectively.

Reverting Console Override

If you need to restore the original native console object after debug-frontend has overridden it, you can use the debug.revertConsoleOverride() method.

import debug from 'debug-frontend';

// Revert the console override
debug.revertConsoleOverride();

// Now, subsequent console.log calls will use the browser's native console
console.log('This message goes to the native console.');

Configuration

Disabling the Runtime UI

In a production environment, you may want to disable the keyboard shortcut for the runtime UI. You can do this by setting the disableShorcut flag on the debug object:

import debug from 'debug-frontend';

debug.disableShorcut = true;

Building

To build the project from source, run the following command. This will generate the UMD and ES Module builds in the dist directory.

npm install
npm run build

Bundle Sizes

The raw minified sizes of the bundles are approximately 12KB each. When served with Gzip compression (common on web servers), the actual transfer sizes are significantly smaller:

• ES Module (dist/index.mjs): ~4.0KB (gzipped)
• UMD (dist/index.js): ~8.0KB (gzipped)

For even smaller sizes, consider Brotli compression. You can test Brotli compression on your system using the brotli command-line tool (if installed):

brotli dist/index.mjs
brotli dist/index.js

Testing

To test the library, you can use the provided test pages. First, start the server:

npm run test

Then, open one of the following pages in your browser:

• http://localhost:3000/index.html (for the ES Module build)
• http://localhost:3000/index-umd.html (for the UMD build)

License

This project is licensed under the ISC License.