🚀 express-terminal-monitor

Zero-dependency, local development API latency and resource profiler middleware for Express.js. Renders a live, flicker-free terminal dashboard (TUI).

express-terminal-monitor is an ultra-lightweight, zero-overhead developer utility that transforms your terminal console into a live dashboard. As requests hit your local Express server, it measures route-by-route execution speed, logs HTTP response status codes, and displays real-time system CPU & memory consumption.

┌──────────────────────────────────────────────────────────┐
│  🚀 EXPRESS API TERMINAL MONITOR                         │
├──────────────────────────────────────────────────────────┤
│  SYSTEM UTILIZATION                                      │
│  CPU Usage  : [████░░░░░░░░░░░░░░░░] 20.0%               │
│  Heap Memory: [██████░░░░░░░░░░░░░░] 150.0 MB / 512 MB   │
│  Total HTTP Requests Processed: 142                      │
├──────────────────────────────────────────────────────────┤
│  ACTIVE ROUTE LATENCIES (Last 100 requests)              │
│  METHOD   ROUTE                      HITS    AVG  MIN/MAX│
│  GET      /api/users/:id             52      12ms 5/45ms │
│  POST     /api/login                 45      48ms 8/92ms │
├──────────────────────────────────────────────────────────┤
│  RESPONSE STATUS DISTRIBUTION                            │
│  2xx Success: [████████████████████] 88.0% (125)          │
│  3xx Redirect: [██░░░░░░░░░░░░░░░░░░] 8.0% (11)           │
│  4xx Client  : [█░░░░░░░░░░░░░░░░░░░] 4.0% (6)            │
│  5xx Server  : [░░░░░░░░░░░░░░░░░░░░] 0.0% (0)            │
└──────────────────────────────────────────────────────────┘

Key Features

• ⚡ Flicker-Free Terminal UI (TUI): Repositions the cursor dynamically using ANSI escape sequences (\x1b[N A) on updates instead of clearing the screen, ensuring smooth, non-flickering redraws.
• 🛣️ Express Route Aggregation: Groups metrics by dynamic Express routes (e.g. /api/users/:id) rather than raw request URLs (e.g. /api/users/123), preventing route list explosion.
• 🛡️ Production Auto-Bypass: Instantly disables console dashboard rendering in production environments (process.env.NODE_ENV === 'production') to maintain standard clean logs.
• 📦 Zero Runtime Dependencies: Pure JS/TS implementation with 0 third-party packages, keeping your application package lightweight and secure.
• ⚙️ Core Telemetry & Profiling: Tracks CPU load, memory utilization (V8 heap allocation), route counts, response codes (2xx/3xx/4xx/5xx), and millisecond precision latencies.

Installation

Install via your preferred package manager:

npm install express-terminal-monitor
# or
yarn add express-terminal-monitor
# or
pnpm add express-terminal-monitor
# or
bun add express-terminal-monitor

Quick Start

Just import and register the middleware in your Express application:

import express from 'express';
import { expressTerminalMonitor } from 'express-terminal-monitor';

const app = express();

// Register the terminal monitor middleware
app.use(expressTerminalMonitor());

app.get('/api/users/:id', (req, res) => {
  res.send({ id: req.params.id, name: 'John Doe' });
});

app.listen(3000, () => {
  console.log('Server started on port 3000');
});

Options

Customize the monitor behavior by passing configuration parameters:

app.use(expressTerminalMonitor({
  /**
   * Refreshes the terminal dashboard every 300ms.
   * Default: 500ms
   */
  intervalMs: 300,

  /**
   * Manually enable or disable the terminal rendering.
   * Default: true (automatically disabled if NODE_ENV === 'production')
   */
  enabled: true
}));

Contributing

We welcome community contributions! Please read our Contributing Guide to set up the development environment, build the TypeScript files, and run tests.

License

MIT © Ezekiel Adejobi