Registry / observability / express-prom-bundle

express-prom-bundle

JSON →
library8.0.0jsnpmunverified

express-prom-bundle is an Express.js middleware designed to integrate popular Prometheus metrics into an application with minimal configuration. It bundles essential metrics, notably `up` and `http_request_duration_seconds`, which can be configured as either a histogram or a summary and labeled with HTTP status codes, methods, and paths. The current stable version is 8.0.0, which requires Express.js v5 and `prom-client` v15 or higher. The library maintains a steady release cadence, incorporating dependabot updates and new features, with major versions typically aligning with peer dependency updates. A key differentiator is its focus on ease of use, providing a consolidated solution for common Express metric needs, as well as features like path normalization and custom label support. Its middleware order dependency allows for selective metric collection, and it explicitly supports both CommonJS and ESM environments, shipping with TypeScript type definitions.

npm install express-prom-bundle
INSTALL
IMPORT
SIG · EXPRESS-PROM-BUNDL
E
express-prom-bundle
observabilityjavascriptv8.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

promBundle
import promBundle from 'express-prom-bundle';
const promBundle = require('express-prom-bundle');
For ESM projects, use the default import. CommonJS `require` is also supported.
register
import { register } from 'prom-client';
const register = require('prom-client').register;
The `register` object from the `prom-client` peer dependency is often needed to expose metrics or add custom ones.
PromBundleOptions
import type { PromBundleOptions } from 'express-prom-bundle';
import { PromBundleOptions } from 'express-prom-bundle';
Use `import type` for type-only imports in TypeScript to avoid accidental runtime side effects and ensure proper tree-shaking.

This example demonstrates how to set up `express-prom-bundle` with an Express application, including basic routes and custom labels, then exposes the metrics endpoint.

import express from 'express'; import promBundle from 'express-prom-bundle'; const app = express(); // Configure the metrics middleware const metricsMiddleware = promBundle({ includeMethod: true, includePath: true, // IMPORTANT: only measures routes registered AFTER this middleware customLabels: { service_name: 'my-express-app' }, promClient: { collectDefaultMetrics: {} } // Collect default Node.js process metrics }); // Register the metrics middleware BEFORE your routes app.use(metricsMiddleware); // Define your application routes app.get('/', (req, res) => { res.send('Hello, Prometheus!'); }); app.get('/api/users/:id', (req, res) => { // Simulate an async operation setTimeout(() => { res.json({ id: req.params.id, name: `User ${req.params.id}` }); }, Math.random() * 200); }); app.get('/error', (req, res) => { res.status(500).send('Internal Server Error'); }); // The /metrics endpoint is automatically exposed by default // Access it at http://localhost:3000/metrics const PORT = process.env.PORT || 3000; app.listen(PORT, () => { console.log(`Express app listening on port ${PORT}`); console.log(`Metrics available at http://localhost:${PORT}/metrics`); });
Debug
Known issues
breakingVersion 8.0.0 of `express-prom-bundle` updates its peer dependency to `express@5`.
fix
Upgrade your `express` installation to `express@5` (e.g., `npm install express@5 @types/express@5`) or downgrade `express-prom-bundle` to a 7.x version.
affects: >=8.0.0
breakingVersion 7.0.0 of `express-prom-bundle` bumped its peer dependency for `prom-client` to `>=15.0.0`.
fix
Ensure `prom-client` is installed at version `15.0.0` or higher (e.g., `npm install prom-client@^15.0.0`). For older `prom-client` versions (v12-v14), you must downgrade `express-prom-bundle` to v6.6.0.
affects: >=7.0.0
gotchaThe order of middleware registration is crucial: only routes registered *after* `express-prom-bundle`'s middleware will be measured.
fix
Always place `app.use(metricsMiddleware)` before any `app.get()`, `app.post()`, etc., definitions that you wish to monitor.
affects: >=1.0.0
gotchaWhile the `metricsPath` option allows customization of the Prometheus metrics endpoint, it is highly recommended to stick to the default `/metrics` path.
fix
Avoid changing `metricsPath` unless there's a strong, specific requirement, as it can cause confusion for standard Prometheus scraping configurations.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'prom-client'
The `prom-client` library is a peer dependency and must be installed explicitly alongside `express-prom-bundle`.
fix
Run `npm install prom-client` or `yarn add prom-client` in your project.
TypeError: Router.use() requires a middleware function but got a Object
This error often indicates a mismatch between your Express.js version and the `express-prom-bundle` version, specifically using `express-prom-bundle` v8.x with `express` v4.x.
fix
Upgrade your `express` installation to `express@5` (e.g., `npm install express@5 @types/express@5`) or downgrade `express-prom-bundle` to a v7.x release.
TypeError: promClient.collectDefaultMetrics is not a function (or similar prom-client API error)
This typically occurs when `express-prom-bundle` (especially v7+) is used with an incompatible, older version of `prom-client` (e.g., prior to v15.0.0).
fix
Ensure that your `prom-client` installation is version `15.0.0` or higher to match the peer dependency requirements of `express-prom-bundle` v7+.
Metrics not appearing for some Express routes when accessing /metrics
The `express-prom-bundle` middleware was registered in Express's middleware chain *after* the routes it should be monitoring.
fix
Ensure that `app.use(metricsMiddleware)` is called *before* any of the `app.get()`, `app.post()`, or other route handlers that you intend to have metrics collected for.
Upgrade
Version history
8.0.0latest on npm
Audit
Dependencies
prom-clientrequiredCore library for Prometheus metrics collection and exposure; required as a peer dependency for all functionality.
expressrequiredThe primary web framework this middleware integrates with.
Agent activity
18 hits · last 30 days
node
14
OpenAI (training)
2
Resources
express-prom-bundle — npm install express-prom-bundle · libregistry