healthcheck-middleware

1.0.1 verified Sat Apr 25 auth: no javascript

An Express middleware for rendering a JSON healthcheck endpoint. v1.0.1 stable. Provides default health info (status, uptime, memory usage), supports custom checks via addChecks (promise-friendly) and custom health info formatting. Lightweight alternative to full monitoring libraries like node-monitor.

Common errors

error TypeError: healthcheck is not a function ↓

cause Using ESM import (import) on CJS-only module, or misspelling require.

fix

Use const healthcheck = require('healthcheck-middleware');

error TypeError: app.use() requires middleware function ↓

cause Passing the factory result (healthcheck()) instead of the factory itself to app.use.

fix

app.use('/healthcheck', healthcheck({...}));

error TypeError: fail is not a function ↓

cause addChecks signature expected (fail, pass) but you used different parameter order or forgot to provide callback.

fix

Add a function that takes two arguments: function(fail, pass) {...}

Warnings

gotcha Empty options object passed but no checks defined; middleware still returns default health info. ↓

fix No fix needed; expected behavior.

gotcha Do NOT call require('healthcheck-middleware') with options at require time — that will return middleware, not export the factory. ↓

fix Use const hc = require('healthcheck-middleware'); then app.use('/healthcheck', hc(options));

gotcha fail() called with no argument results in status 'failure' but no message; may be unexpected if you assume error message always present. ↓

fix Always pass an Error to fail() for consistency.

gotcha pass() with properties named 'status', 'uptime', or 'memoryUsage' will override default values silently. ↓

fix Avoid using those keys in pass data or rename them.

gotcha healthInfo throws an Error? Middleware still returns 200 but with 'warning' in status; may mask configuration issues. ↓

fix Catch errors in healthInfo or ensure no throws.

Install

npm install healthcheck-middleware

yarn add healthcheck-middleware

pnpm add healthcheck-middleware

Imports

healthcheck
```
const healthcheck = require('healthcheck-middleware')
```
CJS default export. No ESM or named exports provided.
healthcheck (as middleware)
wrong
```
app.use('/healthcheck', healthcheck)
```
correct
```
app.use('/healthcheck', healthcheck())
```
healthcheck is a factory function, not a middleware directly.

healthcheck (with options)

wrong

const healthcheck = require('healthcheck-middleware')({ addChecks: ... }); app.use('/healthcheck', healthcheck)

correct

const healthcheck = require('healthcheck-middleware'); app.use('/healthcheck', healthcheck({ addChecks: ... }))

Do not call the factory prematurely; pass options at middleware creation.

Quickstart

Example showing custom checks and health info formatting with Express middleware.

const express = require('express');
const healthcheck = require('healthcheck-middleware');

const app = express();
app.use('/healthcheck', healthcheck({
  addChecks: (fail, pass) => {
    // Simulate async check
    setTimeout(() => {
      if (Math.random() > 0.5) {
        pass({ db: 'connected' });
      } else {
        fail(new Error('Database unreachable'));
      }
    }, 100);
  },
  healthInfo: (info) => ({
    status: info.status,
    uptime: info.uptime,
    custom: 'value'
  })
}));
app.listen(3000);