Fast, composable performance middleware for Express.

Table of contents

• Table of contents
• Installation
• Features
• Docs & Community
• Quick Start
• Philosophy
• Examples
• Contributing
  • Security Issues
  • Running Tests
• License

import express from "express";
import { performanceToolkit } from "express-performance-toolkit";

const app = express();
const toolkit = performanceToolkit();

app.use(toolkit.middleware);

app.listen(3000, () => {
  console.log("Server is running on http://localhost:3000");
});

Installation

Before installing, download and install Node.js. Node.js 20 or higher is required.

Installation is done using the npm install command:

npm install express-performance-toolkit

Features

• Request Caching: High-performance in-memory LRU cache with optional Redis backend for persistent scaling.
• Response Compression: Automatic Gzip/Deflate/Brotli compression to minimize bandwidth usage.
• Smart Rate Limiting: IP-based protection with real-time tracking of blocked traffic.
• Slow Request Detection: Built-in observability with structured logging and performance alerts.
• Webhook Alerting: Smart edge-triggered notifications for Slack, Discord, and custom integrations to prevent alert fatigue.
• Health Check: Top-level lightweight JSON endpoint for liveness/readiness orchestration probes.
• Request Tracing: Automatic generation and propagation of X-Request-Id for distributed tracing.
• N+1 Query Tracking: Effortlessly detect inefficient database patterns with simple instrumentation.
• Performance Dashboard: A sleek, real-time UI to monitor your server's health, throughput, and anomalies.
• Metrics Export: Expose application and system metrics in Prometheus format (default: /ept/metrics) for Grafana and OTEL compatibility.
• Metrics History: Automatic time-series snapshots for visualizing throughput, latency, and resource trends over time.

Docs & Community

• Documentation
• GitHub Repository
• NPM Package
• Medium Article

Quick Start

The quickest way to get started is to wrap your application with the toolkit:

const toolkit = performanceToolkit({
  cache: { ttl: 30000, maxSize: 50 },
  compression: {
    enabled: true,
    threshold: 1024,
  },
  logging: {
    slowRequestThreshold: 500,
    file: "logs/ept.log",
    rotation: true,
    maxDays: 7,
  },
  rateLimit: {
    enabled: true,
    windowMs: 1000,
    max: 100,
  },
  dashboard: {
    enabled: true,
    path: "/ept", // Dashboard automatically mounted here
    auth: { username: "admin", password: "ept-toolkit" }, // Default credentials
    exporter: { enabled: true, path: "/metrics", requireAuth: false }, // Prometheus export
  },
  health: {
    enabled: true,
    path: "/health",
  },
  alerts: {
    webhooks: [process.env.SLACK_WEBHOOK_URL],
    rules: [{ metric: "avgResponseTime", threshold: 1500 }]
  },
  tracing: {
    enabled: true, // default true
    headerName: "x-request-id", // default x-request-id
  },
  history: {
    enabled: true,
    intervalMs: 30000, // Snapshot every 30s
    maxPoints: 60, // Keep 30 mins of history
  },
});

// This single line handles both performance logic AND the dashboard!
app.use(toolkit.middleware);

View the dashboard at: http://localhost:3000/ept

API Reference

performanceToolkit(options?)

The main entry point for the toolkit. It returns a ToolkitInstance object.

ToolkitOptions

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | cache | CacheOptions | false | LRU caching configuration. | | compression | CompressionOptions | true | Response compression settings. | | logging | LoggerOptions | true | Structured logging & slow request detection. | | rateLimit | RateLimitOptions | false | IP-based rate limiting. | | dashboard | DashboardOptions | true | Real-time UI dashboard. | | health | HealthCheckOptions | true | Liveness/Readiness JSON endpoint. | | alerts | AlertOptions | false | Webhook notifications for performance anomalies. | | tracing | TracingOptions | true | Distributed tracing (Request IDs). | | history | HistoryOptions | true | Time-series metrics history. |

ToolkitInstance

The object returned by performanceToolkit().

• middleware: The Express middleware to be used with app.use().
• store: The MetricsStore instance for programmatic access to raw metrics.

Instrumentation

N+1 Query Tracking

Inject tracking into your data layer to detect inefficient patterns:

app.get('/users', async (req, res) => {
  const users = await db.users.find();
  
  for (const user of users) {
    // Each call increments the query count for this request
    req.ept.trackQuery('User Profile Fetch');
    await db.profiles.find({ userId: user.id });
  }
  
  res.json(users);
});

The toolkit will automatically flag this route in the dashboard if the number of queries exceeds your configured threshold.

Philosophy

The Express Performance Toolkit (EPT) philosophy is to provide robust, zero-config performance optimizations and observation tools that "just work". It's designed to be lightweight, resilient (graceful fallbacks), and highly actionable for developers building modern Express APIs.

Examples

To view the examples, clone the repository:

git clone https://github.com/Sainimayank1/express-performance-toolkit.git --depth 1
cd express-performance-toolkit

Then install dependencies and run the example server:

npm install
npm run example

Contributing

The project welcomes all constructive contributions!

Security Issues

If you discover a security vulnerability, please open an issue in the GitHub repository.

Running Tests

To run the test suite, first install the dependencies:

npm install

Then run npm test:

npm test

License

GNU