npm package: @ninjacut/ninja-logger
Description: Standalone development logging tool with real-time web UI
Latest version: 1.4.1

# 🥷 Ninja Logger

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

![Version](https://img.shields.io/npm/v/@ninjacut/ninja-logger)
![License](https://img.shields.io/npm/l/@ninjacut/ninja-logger)
![Downloads](https://img.shields.io/npm/dt/@ninjacut/ninja-logger)
![Size](https://img.shields.io/bundlephobia/min/@ninjacut/ninja-logger)

**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.

```bash
npm install -g @ninjacut/ninja-logger
```

### 2. Install Locally (The Client)

Install the library in your project to send logs.

```bash
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:

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

### Step 2: Add Logs to Your Code

Import `ninjalog` and start sending data immediately.

```typescript
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.

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

---

## Configuration

### CLI Options

Customize the server when running `ninja-logger`:

```bash
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:

```bash
# 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`.

```typescript
// 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

![Ninja Logger Web UI](./preview.png)

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](https://github.com/NinjaCutApp/ninja-logger).

## License

MIT © [NinjaCut](https://github.com/NinjaCutApp)