nodejs-health-checker

Contributors

Made with contributors-img.

Table of Contents

• nodejs-health-checker
  • Contributors
    • Table of Contents
  • How to install
  • Available integrations
    • Redis
    • Web integration (HTTPS)
    • AWS DynamoDB
    • Databases
    • Custom Integration Support
  • How to use (Express Example)
    • Kubernetes Integration

CHANGELOG

This Node.js package allows you to monitor the health of your application. It provides two levels of health checking:

1. Simple Check (Liveness): Confirms the application is online and responding. It does not check external integrations. Response Example:

{
  "status": "fully functional"
}

2. Detailed Check (Readiness): Verifies if the application and all configured integrations (databases, caches, APIs) are operational. Response Example:

{
    "name": "My node application",
    "version": "1.0.0",
    "status": true,
    "date": "2026-03-10T15:29:41.616Z",
    "duration": 0.523,
    "integrations": [
        {
            "name": "redis integration",
            "kind": "Redis DB integration",
            "status": true,
            "response_time": 0.044,
            "url": "redis:6379"
        },
        {
            "name": "my web api integration",
            "kind": "Web integrated API",
            "status": true,
            "response_time": 0.511,
            "url": "[https://github.com/status](https://github.com/status)"
        }
    ]
}

How to install

npm i nodejs-health-checker

Available integrations

• [x] Redis (optional)
• [x] Memcached (optional)
• [x] Web integration (HTTPS)
• [x] AWS DynamoDB (optional)
• [x] Databases (via Sequelize) (optional) - Authored by @MikeG96
• [x] Custom integration support - Authored by @youngpayters

The optional integrations require additional peer dependencies. If an integration is configured but its package is missing, the check will return ERR_MODULE_NOT_FOUND:

{
  "name": "example-missing-packages",
  "status": false,
  "integrations": [
    {
      "name": "test redis",
      "kind": "Redis DB integration",
      "status": false,
      "error": { "code": "ERR_MODULE_NOT_FOUND" }
    }
  ]
}

Redis

Requires the redis package:

npm i nodejs-health-checker redis

import { HealthcheckerDetailedCheck, HealthTypes } from "nodejs-health-checker";

HealthcheckerDetailedCheck({
  name: "My application",
  version: "1.0.0",
  integrations: [
     {
       type: HealthTypes.Redis,
       name: "redis integration",
       host: "redis",
       port: 6379
     }
  ],
}).then(console.log).catch(console.error);

See more options in the IntegrationConfig interface.

Web integration (HTTPS)

Uses the native fetch API. No extra dependencies required.

{
  type: HealthTypes.Web,
  name: "external api",
  host: "[https://api.example.com/status](https://api.example.com/status)"
}

AWS DynamoDB

Requires @aws-sdk/client-dynamodb:

npm i nodejs-health-checker @aws-sdk/client-dynamodb

Databases

Uses Sequelize v6 as a peer dependency. You must install the driver for your specific database (Postgres, MySQL, or MariaDB).

Postgres Example:

npm i nodejs-health-checker sequelize pg pg-hstore

{
  type: HealthTypes.Database,
  name: "postgres db",
  host: "localhost",
  dbPort: 5432,
  dbName: "my_db",
  dbUser: "admin",
  dbPwd: "password",
  dbDialect: Dialects.postgres,
}

Custom Integration Support

You can provide a custom validation function for any dependency not supported out of the box:

import { HealthcheckerDetailedCheck, HealthTypes, HTTPChecker } from "nodejs-health-checker";

async function myValidation(): Promise<HTTPChecker> {
  // Your custom logic here
  return { status: true };
}

HealthcheckerDetailedCheck({
  integrations: [
    {
      type: HealthTypes.Custom,
      name: "my custom check",
      customCheckerFunction: myValidation,
    }
  ]
});

How to use (Express Example)

import express from "express";
import { HealthcheckerDetailedCheck, HealthcheckerSimpleCheck, HealthTypes } from "nodejs-health-checker";

const server = express();

// Liveness probe
server.get("/health/liveness", (_, res) => {
  res.send(HealthcheckerSimpleCheck());
});

// Readiness probe
server.get("/health/readiness", async (_, res) => {
  const health = await HealthcheckerDetailedCheck({
    name: "My App",
    version: "1.0.0",
    integrations: [
      {
        type: HealthTypes.Redis,
        name: "main-cache",
        host: "localhost",
      }
    ],
  });
  res.status(health.status ? 200 : 503).send(health);
});

server.listen(3000);

Kubernetes Integration

To use this with Kubernetes, configure your Deployment probes as follows:

livenessProbe:
  httpGet:
    path: /health/liveness
    port: 3000
readinessProbe:
  httpGet:
    path: /health/readiness
    port: 3000