@alkeshgupta/LogGuard

A next-generation, developer-friendly logging library for Node.js and browsers. LogGuard makes logging easy, beautiful, and configurable with themes, tags, timestamps, caller info, and a single toggle to enable/disable logging.

✨ Features

• Level-based Logging: trace, debug, info, success, warn, error.
• Single Switch Enable/Disable: Turn off all logs in production with a simple config change
• Themes & Styles: Fully customizable themes for browser & terminal: minimal, forest, neon, candy, cyberpunk, ocean, sunset, retro
• Tags Support: Suggestion-based tags like log.tags.DB and log.tags.AUTH. Only enabled tags are printed.
• Timestamps & Caller Info: Optional timestamps and caller info for quick debugging.
• Cross-Environment Support: Works seamlessly in Node.js and React/browser.
• Flexible Configuration: Global settings through logguard.config.js or dynamically via log.setConfig().

📦 Installation

npm install @alkeshgupta/logguard

or

yarn add @alkeshgupta/logguard

📝 Basic Usage

🧠 Node.js

const { log } = require("@alkeshgupta/logguard");

log.trace("Trace message");
log.debug("Debug message");
log.info("Info message");
log.success("Operation successful!");
log.warn("Warning issued");
log.error("An error occurred");

⚛️ React Usage Example

Works anywhere inside your components.

import {log} from "@alkeshgupta/logguard";
import { useEffect } from "react";
import config from "../logguard.config";

useEffect(() => {
  // Dynamic config in browser
  log.setConfig(config);

  log.success("App Mounted Successfully!");
  log.info(, "Database connected");
}, []);

⚙️ Configuration (logguard.config.js)

LogGuard can be fully customized through a logguard.config.js file in your project root. This allows you to control log levels, themes, timestamps, caller info, and tag behavior across Node.js and browser environments.

Example Configuration

export default {
  logGuardEnabled: true,            // Single Point of Enablement/Disablement of logs
  loglevel: "debug",                // Minimum level of logs to display
  timestamp: {
    show: true,                     // Show timestamps in logs
    utc: false                      // Use UTC time format (true) or local time (false)
  },
  caller: {
    show: true                      // Display caller info (file & line number)
  },
  theme: "minimal",                 // Theme for log styling: minimal, forest, neon, candy, cyberpunk, ocean, sunset, retro
  tags: {
    show: true
    allowed: ["DB", "AUTH", "API"], // Tags which the user wants to use
    enabled: ["DB", "API"]          // Only logs with these enabled tags will be printed
  }
};

Detailed Option Description

| Option | Type | Default | Description | | ----------------- | ----------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | logGuardEnabled | boolean | true | Directly enable/disable all the logs. | | loglevel | string (trace | debug | info | success | warn | error) | debug | Minimum level of logs that will be printed. All levels above this will also be shown. | | timestamp.show | boolean | true | Whether to display timestamps for each log message. | | timestamp.utc | boolean | false | If true, timestamps are shown in UTC; otherwise, local time is used. | | caller.show | boolean | true | Whether to display the caller file and line number for each log. Only the last folder, file name and line number are shown for brevity. | | theme | string | minimal | Theme for styling logs in both Node and browser. Options: minimal, forest, neon, candy, cyberpunk, ocean, sunset, retro. | | tags.show | boolean | true | Whether to display the tag for each log. | | tags.allowed | array of strings | [] | Tags which the user wants to use. It's recommended to mention the used tags in here for peers to know. | | tags.enabled | array of strings | [] | Only logs with these enabled tags will be printed. If a log is sent with a tag not in this list, it will be ignored. |

✅ Enable / Disable Logging

• Enable all logs: logGuardEnabled: true

• Disable all logs: logGuardEnabled : false — perfect for production!

🎨 Themes

• Available for Node and Browser: minimal, forest, neon, candy, cyberpunk, ocean, sunset, retro

• Each theme comes with custom colors for every log level, both for text and background.

🔖 Tags

Use tags for categorizing logs:

log.success("DB", "Database initialized"); // Here, the tag is "DB"
log.warn("AUTH", "Unauthorized login attempt"); // And here, its "AUTH"

• Available for Node and Browser: minimal, forest, neon, candy, cyberpunk, ocean, sunset, retro

• Each theme comes with custom colors for every log level, both for text and background.

Notes

1. Dynamic Configuration: You can also override these settings at runtime in React or browser projects using:

log.setConfig({
  loglevel: "warn",
  timestamp: { show: false },
  caller: { show: true },
  ...
});

2. Tags Behavior:

   • Suggested tags: Listed in allowed Tags for peers to know.
   • Enabled tags: Only these tags are printed to the console. Logs without a tag are always printed.

3. Themes:

   • Themes affect both browser and Node styling.
   • Each theme defines text colors and background colors for each log level.

4. Log Level Hierarchy:

trace < debug < info < success < warn < error

Setting loglevel: "info" will skip trace and debug logs.

⚡ Why LogGuard?

• Unified experience: Same config for Node and Browser.
• Clean and readable logs: Colored badges, optional timestamps, and caller info.
• Developer productivity: Tags based filtering, themes, and log level management.
• Production-ready: Single toggle to disable logs without touching code.

📄 License

MIT License © 2025 Alkesh Gupta
Feel free to use, modify, and distribute.

⭐ Support

If you like this library, consider:

• leaving a GitHub & npm star ⭐
• reporting issues
• contributing ideas