Simple Express Healthcheck Middleware

0.1.0 verified Thu Apr 23 auth: no javascript abandoned

express-healthcheck is a lightweight middleware designed to provide basic health check endpoints for Express.js applications. Released as version 0.1.0 over ten years ago (last published in March 2016), the package is currently unmaintained and effectively abandoned by its original author. It offers a minimal interface to expose an uptime metric and allows for custom `healthy` and `test` functions to provide more application-specific health status, returning a 200 status code with a JSON payload. Unlike more modern and actively maintained health check libraries, it lacks features such as detailed dependency checks, async/await support, built-in security mechanisms, or explicit ESM compatibility, making it suitable only for extremely simple monitoring scenarios or as a historical reference.

Common errors

error TypeError: expressHealthcheck is not a function ↓

cause The `express-healthcheck` module exports a function that needs to be invoked to return the actual middleware. It's often mistakenly used directly without calling it.

fix

Ensure you call the imported module: app.use('/health', require('express-healthcheck')()); or app.use('/health', expressHealthcheck()); if you've assigned the result of require() to expressHealthcheck.

error ERR_REQUIRE_ESM ↓

cause Attempting to `import` a CommonJS-only module (`express-healthcheck`) in an ES module context without proper Node.js configuration or transpilation.

fix

Revert to CommonJS require() syntax: const expressHealthcheck = require('express-healthcheck');. If you must use ESM for your project, consider using a more modern health check library that offers explicit ESM support.

Warnings

breaking The `express-healthcheck` package is effectively abandoned, with its last release (v0.1.0) dating back to March 2016. It does not receive security updates, bug fixes, or feature enhancements. Using unmaintained software can expose your application to security vulnerabilities and compatibility issues with newer Node.js or Express versions. ↓

fix Consider migrating to actively maintained health check middleware packages like `express-healthchecker`, `express-actuator-healthcheck`, or implementing custom health check logic for better control and security.

gotcha This package is CommonJS-only. Attempting to import it using ES module `import` syntax (e.g., `import expressHealthcheck from 'express-healthcheck';`) in an ES module context will result in runtime errors like `ERR_REQUIRE_ESM` unless Node.js is specifically configured for CJS-ESM interoperability or a transpilation step is used. ↓

fix Always use `const expressHealthcheck = require('express-healthcheck');` for this package. If using TypeScript, `import expressHealthcheck = require('express-healthcheck');` is the most robust option, or ensure `esModuleInterop` is enabled in your `tsconfig.json` to allow `import expressHealthcheck from 'express-healthcheck';`.

gotcha The `test` function provided to `express-healthcheck` for custom logic does not inherently support Promises or async/await. It expects either a synchronous return, a thrown error, or a callback invocation to signal health status. Modern asynchronous operations might not integrate seamlessly without wrapping. ↓

fix If your health check logic involves asynchronous operations (e.g., database queries, external API calls), you must wrap them to fit the expected synchronous return or callback pattern. For complex async checks, a more modern health check library or custom middleware would be more appropriate.

Install

npm install express-healthcheck

yarn add express-healthcheck

pnpm add express-healthcheck

Imports

expressHealthcheck
wrong
```
import expressHealthcheck from 'express-healthcheck';
```
correct
```
const expressHealthcheck = require('express-healthcheck');
```
This package is CommonJS-only. Direct ESM imports will fail unless Node.js is configured for interoperability or the code is transpiled. Use `require()` for compatibility.
MiddlewareUsage
wrong
```
app.use('/health', require('express-healthcheck'));
```
correct
```
app.use('/health', require('express-healthcheck')());
```
The `express-healthcheck` module exports a function that must be immediately invoked `()` to return the actual middleware, which can then be used with `app.use()`.
TypeScriptTypes
wrong
```
import { RequestHandler } from 'express-healthcheck';
```
correct
```
import expressHealthcheck = require('express-healthcheck');
// or if esModuleInterop is true:
import expressHealthcheck from 'express-healthcheck';
```
While `@types/express-healthcheck` exists, the original package does not ship with its own types. The type definitions typically use `export =` syntax, requiring `import = require()` or `esModuleInterop: true` for default import syntax.

Quickstart

Demonstrates setting up a basic health check and a customized health check endpoint with `express-healthcheck` in an Express application. It includes a simulated asynchronous test for a dependency and a custom healthy response.

const express = require('express');
const expressHealthcheck = require('express-healthcheck');
const app = express();

// Basic health check endpoint
app.use('/health', expressHealthcheck());

// Custom health check with a test function
app.use('/custom-health', expressHealthcheck({
  test: function () {
    // Simulate a dependency check, e.g., database connection
    const isDatabaseHealthy = Math.random() > 0.1;
    if (!isDatabaseHealthy) {
      throw new Error('Database connection failed');
    }
    return { status: 'Database OK' };
  },
  healthy: function () {
    return { service: 'healthy', timestamp: new Date().toISOString() };
  }
}));

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log(`Basic health check at http://localhost:${PORT}/health`);
  console.log(`Custom health check at http://localhost:${PORT}/custom-health`);
});