🥷 Ninja Logger

The Ultimate Real-Time Node.js Logging Tool & Web UI

Ninja Logger is a standalone, real-time log viewer and debugging tool for Node.js applications. It instantly upgrades your development workflow by replacing messy console logs with a beautiful, searchable Web UI.

Stop digging through terminal text. Start logging like a ninja. 🥷

Why Ninja Logger?

Perfect for developers who need:

• Real-time visibility into long-running processes (API servers, scrapers, AI pipelines).
• Grouped logging to organize logs by microservice, module, or function.
• Rich data inspection for JSON objects, arrays, and errors without [Object object].
• Zero-config setup that works instantly with any Node.js project.

Features

• Real-Time WebSockets: Logs appear instantly in your browser via Socket.IO.
• Powerful Filters: Search text, filter by log level (Info, Success, Warning, Error), or isolate specific groups.
• Smart Grouping: Organize logs by categories like API, Database, CronJob.
• Beautiful Web UI: Clean, dark-mode interface with collapsible groups and JSON highlighting.
• Zero-Dependency Client: The logging client is lightweight and won't bloat your app.
• Production Safe: Auto-disables in production environments with zero overhead.
• Hot Reload Friendly: Designed to work seamlessly with nodemon and other dev tools.

Installation

1. Install Globally (The Server)

Install the CLI tool globally to run the log viewer server anywhere.

npm install -g @ninjacut/ninja-logger

2. Install Locally (The Client)

Install the library in your project to send logs.

npm install --save-dev @ninjacut/ninja-logger

Quick Start

Step 1: Start the Log Server

Run the following command in a terminal to start the Web UI:

ninja-logger
# Server started at http://localhost:4444

Step 2: Add Logs to Your Code

Import ninjalog and start sending data immediately.

import { ninjalog } from "@ninjacut/ninja-logger/client";

// Basic logging
ninjalog("info", "AuthService", "User logged in successfully");

// Log rich data objects
ninjalog("debug", "OrderProcessor", "Processing order", {
  orderId: "ORD-123",
  items: ["Item A", "Item B"],
  total: 99.99,
});

// Log errors with stack traces
try {
  throw new Error("Payment gateway timeout");
} catch (err) {
  ninjalog("error", "PaymentAPI", err);
}

// Success messages
ninjalog("success", "Database", "Connection established", { host: "127.0.0.1" });

Step 3: Watch the Magic

Open http://localhost:4444 in your browser. You'll see your logs streaming in live!

API Reference

ninjalog(level, group, ...data)

Sends a log message to the running Ninja Logger server.

| Parameter | Type | Description | | --------- | -------- | ---------------------------------------------------------------------- | | level | string | Log severity: 'success', 'info', 'warning', 'error', 'debug' | | group | string | Category name for grouping logs (e.g., 'API', 'DB') | | ...data | any[] | Any number of arguments (objects, strings, arrays, errors) |

disconnect()

Manually closes the socket connection. Useful for cleanup in testing scripts.

import { disconnect } from "@ninjacut/ninja-logger/client";
disconnect();

Configuration

CLI Options

Customize the server when running ninja-logger:

ninja-logger --port 5000 --host 0.0.0.0

| Option | Default | Description | | ------------ | ----------- | ----------------------------- | | -p, --port | 4444 | Port to run the Web UI server | | -h, --host | localhost | Host address to bind to |

Environment Variables

Configure the client via .env or environment variables:

# Connect to a custom server
NINJA_LOGGER_PORT=5000
NINJA_LOGGER_HOST=192.168.1.50

# Force enable in production (use with caution)
NINJA_LOGGER_FORCE=true

# Force disable logging (e.g. in CI/CD)
NINJA_LOGGER_DISABLED=true

Best Practices

Production Safety

Ninja Logger is auto-disabled if NODE_ENV is not set to development. This prevents accidental connection attempts in production.

To use it in non-development environments, you must explicitly set NINJA_LOGGER_FORCE=true.

// It's safe to leave ninjalog() calls in your code!
// They will simply do nothing in production unless forced.
ninjalog("info", "App", "This logs in dev, but is silent in prod");

Screenshots

The Web UI features a robust set of tools for debugging:

• Filters: Toggle visibility of Success, Info, Warning, Error logs.
• Search: Real-time fuzzy search through all log data.
• Collapse All: Quickly collapse groups to see the big picture.
• Auto-Scroll: Keep up with the latest logs or pause to inspect details.

Contributing

We love contributions! Please feel free to submit a Pull Request on GitHub.

License

MIT © NinjaCut