{"id":17130,"library":"express-prom-bundle","title":"Prometheus Metrics for Express","description":"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.","status":"active","version":"8.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/jochen-schweizer/express-prom-bundle","tags":["javascript","prometheus","metrics","express","path","method","typescript"],"install":[{"cmd":"npm install express-prom-bundle","lang":"bash","label":"npm"},{"cmd":"yarn add express-prom-bundle","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-prom-bundle","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core library for Prometheus metrics collection and exposure; required as a peer dependency for all functionality.","package":"prom-client","optional":false},{"reason":"The primary web framework this middleware integrates with.","package":"express","optional":false}],"imports":[{"note":"For ESM projects, use the default import. CommonJS `require` is also supported.","wrong":"const promBundle = require('express-prom-bundle');","symbol":"promBundle","correct":"import promBundle from 'express-prom-bundle';"},{"note":"The `register` object from the `prom-client` peer dependency is often needed to expose metrics or add custom ones.","wrong":"const register = require('prom-client').register;","symbol":"register","correct":"import { register } from 'prom-client';"},{"note":"Use `import type` for type-only imports in TypeScript to avoid accidental runtime side effects and ensure proper tree-shaking.","wrong":"import { PromBundleOptions } from 'express-prom-bundle';","symbol":"PromBundleOptions","correct":"import type { PromBundleOptions } from 'express-prom-bundle';"}],"quickstart":{"code":"import express from 'express';\nimport promBundle from 'express-prom-bundle';\n\nconst app = express();\n\n// Configure the metrics middleware\nconst metricsMiddleware = promBundle({\n  includeMethod: true,\n  includePath: true, // IMPORTANT: only measures routes registered AFTER this middleware\n  customLabels: { service_name: 'my-express-app' },\n  promClient: { collectDefaultMetrics: {} } // Collect default Node.js process metrics\n});\n\n// Register the metrics middleware BEFORE your routes\napp.use(metricsMiddleware);\n\n// Define your application routes\napp.get('/', (req, res) => {\n  res.send('Hello, Prometheus!');\n});\n\napp.get('/api/users/:id', (req, res) => {\n  // Simulate an async operation\n  setTimeout(() => {\n    res.json({ id: req.params.id, name: `User ${req.params.id}` });\n  }, Math.random() * 200);\n});\n\napp.get('/error', (req, res) => {\n  res.status(500).send('Internal Server Error');\n});\n\n// The /metrics endpoint is automatically exposed by default\n// Access it at http://localhost:3000/metrics\nconst PORT = process.env.PORT || 3000;\napp.listen(PORT, () => {\n  console.log(`Express app listening on port ${PORT}`);\n  console.log(`Metrics available at http://localhost:${PORT}/metrics`);\n});\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Version 8.0.0 of `express-prom-bundle` updates its peer dependency to `express@5`.","severity":"breaking","affected_versions":">=8.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.","message":"Version 7.0.0 of `express-prom-bundle` bumped its peer dependency for `prom-client` to `>=15.0.0`.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Always place `app.use(metricsMiddleware)` before any `app.get()`, `app.post()`, etc., definitions that you wish to monitor.","message":"The order of middleware registration is crucial: only routes registered *after* `express-prom-bundle`'s middleware will be measured.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Avoid changing `metricsPath` unless there's a strong, specific requirement, as it can cause confusion for standard Prometheus scraping configurations.","message":"While the `metricsPath` option allows customization of the Prometheus metrics endpoint, it is highly recommended to stick to the default `/metrics` path.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Run `npm install prom-client` or `yarn add prom-client` in your project.","cause":"The `prom-client` library is a peer dependency and must be installed explicitly alongside `express-prom-bundle`.","error":"Error: Cannot find module 'prom-client'"},{"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.","cause":"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.","error":"TypeError: Router.use() requires a middleware function but got a Object"},{"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+.","cause":"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).","error":"TypeError: promClient.collectDefaultMetrics is not a function (or similar prom-client API error)"},{"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.","cause":"The `express-prom-bundle` middleware was registered in Express's middleware chain *after* the routes it should be monitoring.","error":"Metrics not appearing for some Express routes when accessing /metrics"}],"ecosystem":"npm","meta_description":null}