logsave-hub 🚀

logsave-hub is an ethical, easy-to-use logging utility for Node.js that supports both automatic console logging and explicit log APIs, with full ESM + CommonJS compatibility.

It is designed to be:

• ✅ Beginner-friendly
• ✅ Explicit & ethical (no hidden side effects)
• ✅ Works in both ESM and CJS
• ✅ Production-ready
• ✅ Built with TypeScript

✨ Features

• 📁 Automatically creates a log directory
• 🕒 Timestamped daily log files
• 🖥 Optional console.log / warn / error override
• ✍️ Explicit logging API (log.save, log.warn, log.error)
• 🔄 Works in ESM and CommonJS
• 🔒 No cloud upload, no data sharing — local only
• 🗑 Automatic log retention & cleanup (optional, default: 30 days)
• 📊 Built-in live web dashboard for real-time log viewing
• 🔌 Easy integration with Express + Socket.IO via dashboardRouter and attachDashboard

📦 Installation

Install using npm:

npm install logsave-hub

You'll also need express and socket.io if you want to use the live dashboard:

npm install express socket.io

🚀 Basic Usage

logsave-hub exposes two modes:

1. Console override mode (automatic)
2. Explicit logging mode (log.save())

You must explicitly initialize logging using enableLogging().

1️⃣ Console Override Mode (Automatic Logging)

In this mode, all console.log, console.warn, and console.error are automatically written to log files.

▶️ ESM Example

import enableLogging from "logsave-hub";

enableLogging({
  override: true,
  outDir: "./logs"
});

console.log("Server started");
console.warn("Low memory");
console.error("Something went wrong");

▶️ CommonJS Example

const enableLogging = require("logsave-hub");

enableLogging({
  override: true,
  outDir: "./logs"
});

console.log("Server started");
console.warn("Low memory");
console.error("Something went wrong");

2️⃣ Explicit Logging Mode (log.save())

In this mode, the console is not overridden. You explicitly control what gets logged.

▶️ ESM Example

import enableLogging, { log } from "logsave-hub";

enableLogging({
  override: false,
  outDir: "./logs"
});

log.save("Application started");
log.warn("Cache is almost full");
log.error("Database connection failed");

▶️ CommonJS Example

const enableLogging = require("logsave-hub");
const { log } = require("logsave-hub");

enableLogging({
  override: false,
  outDir: "./logs"
});

log.save("Application started");
log.warn("Cache is almost full");
log.error("Database connection failed");

🗂 Log Output

Logs are written to the specified directory (default: ./logs):

logs/
└─ app-2025-12-19.log

Example log content:

2025-12-19 17:16:21 [INFO] Server started
2025-12-19 17:16:31 [WARN] Cache is almost full
2025-12-19 17:16:41 [ERROR] Database connection failed

🗑 Log Retention

logsave-hub can automatically clean up old log files so your logs directory doesn't grow indefinitely.

• Retention period: 30 days by default when enabled
• Runs once on startup, then on a recurring schedule
• Fails silently — retention cleanup will never crash your app
• Disable it by setting retention: false

📊 Live Web Dashboard

logsave-hub ships with a built-in real-time dashboard for viewing your logs in the browser — just mount the router and attach it to a Socket.IO server.

Features:

• 🔴 Live streaming of new log entries via WebSockets
• 📁 Browse and view historical daily log files
• 🔍 Search and filter logs by level (Info / Warn / Error)
• 📈 Live session stats (total / info / warn / error counts)
• 📱 Responsive layout for desktop and mobile

▶️ ESM Example

import express from "express";
import { Server } from "socket.io";
import http from "http";
import enableLogging, { attachDashboard, dashboardRouter } from "logsave-hub";

const app = express();
const server = http.createServer(app);
const io = new Server(server);

attachDashboard(io);
app.use("/logsave-hub", dashboardRouter);

enableLogging({
  override: true,
  outDir: "./logs",
  retention: false
});

server.listen(3000, () => {
  console.log("Listening on port 3000");
});

console.log("Server started");
console.warn("Server started");
console.error("Server started");

▶️ CommonJS Example

const enableLogging = require("logsave-hub").default;
const { log, dashboardRouter, attachDashboard } = require("logsave-hub");
const express = require("express");
const { Server } = require("socket.io");
const http = require("http");

const app = express();
const server = http.createServer(app);
const io = new Server(server);

attachDashboard(io);
app.use("/logsave-hub", dashboardRouter);

enableLogging({
  override: true,
  outDir: "./logs",
  retention: true,
});

console.log("Server started");
console.warn("Server started");
console.error("Server started");

server.listen(3000);

setInterval(() => {
  log.save("Ping at", new Date().toISOString());
  log.warn("Ping at", new Date().toISOString());
  log.error("Ping at", new Date().toISOString());
}, 10000);

Once running, open http://localhost:3000/logsave-hub (or whichever path you mounted the router on) to view the live dashboard.

⚙️ Configuration Options

enableLogging({
  override?: boolean;   // default: true
  outDir?: string;      // default: "./logs"
  retention?: boolean;  // default: true
});

| Option | Description | |-------------|------------| | override | Whether to override console.log | | outDir | Directory where logs are stored | | retention | Whether to automatically purge old log files |

❗ Important Notes

• enableLogging() must be called before using log.save()
• Calling enableLogging() multiple times is safe
• Logs are stored locally only
• No network, no cloud, no tracking

🧠 Why logsave-hub?

Many loggers either:

• Are too complex ❌
• Don't support both ESM & CJS ❌

logsave-hub is designed to be:

• Explicit
• Predictable
• Easy to integrate
• Safe for beginners and professionals

🧪 Supported Environments

• Node.js 20+
• Node.js 22+
• Node.js 24+

📜 License

MIT © Koda Adam

❤️ Contributing

Pull requests and suggestions are welcome. This package is built for the community.