nest-healthkit

Why nest-healthkit

nest-healthkit is a decorator-first health check module for NestJS. It gives you /health/live, /health/ready, optional /health/ui, built-in indicators, and auto-discovered custom checks with almost no wiring. It sits above lower-level health tooling and packages the common health endpoint setup into one module.

Installation

npm install nest-healthkit

Quick Start

import { Module } from '@nestjs/common';
import { HealthkitModule } from 'nest-healthkit';

import { PrismaService } from './prisma.service';

@Module({
  imports: [
    HealthkitModule.forRoot({
      ui: true,
      cacheTtl: 5000,
      indicators: {
        prisma: { prismaToken: PrismaService, name: 'postgres' },
        redis: { redisToken: 'REDIS_CLIENT' },
        memory: { heapThreshold: 400 * 1024 * 1024 },
      },
    }),
  ],
})
export class AppModule {}

Configuration Reference

| Option | Type | Default | Description | |---|---|---|---| | path | string | 'health' | Route prefix used for all health endpoints. | | ui | boolean | false | Enables the HTML dashboard at /{path}/ui. | | authHeaders | Record<string, string> | undefined | Required request headers for all health endpoints. | | timeout | number | 5000 | Per-check timeout in milliseconds. | | cacheTtl | number | 0 | Result cache TTL in milliseconds. | | indicators.prisma | PrismaIndicatorOptions | undefined | Enables the Prisma indicator. | | indicators.typeorm | TypeOrmIndicatorOptions | undefined | Enables the TypeORM indicator. | | indicators.redis | RedisIndicatorOptions | undefined | Enables the Redis indicator. | | indicators.http | HttpIndicatorOptions \| HttpIndicatorOptions[] | undefined | Enables one or more HTTP checks. | | indicators.memory | MemoryIndicatorOptions | undefined | Enables the memory indicator. | | indicators.disk | DiskIndicatorOptions | undefined | Enables the disk indicator. |

Built-in Indicators

Prisma

HealthkitModule.forRoot({
  indicators: {
    prisma: { prismaToken: PrismaService, name: 'postgres' },
  },
});

TypeORM

HealthkitModule.forRoot({
  indicators: {
    typeorm: { connectionName: 'default', name: 'typeorm' },
  },
});

Redis

HealthkitModule.forRoot({
  indicators: {
    redis: { redisToken: 'REDIS_CLIENT', name: 'redis' },
  },
});

HTTP

HealthkitModule.forRoot({
  indicators: {
    http: [
      { url: 'https://api.example.com/health', name: 'public-api' },
      { url: 'https://internal.example.com/status', name: 'internal-api', expectedStatus: 204 },
    ],
  },
});

Memory

HealthkitModule.forRoot({
  indicators: {
    memory: {
      heapThreshold: 300 * 1024 * 1024,
      heapCritical: 500 * 1024 * 1024,
    },
  },
});

Disk

HealthkitModule.forRoot({
  indicators: {
    disk: {
      path: '/',
      thresholdPercent: 0.8,
      criticalPercent: 0.95,
    },
  },
});

Custom Checks with @RegisterHealthCheck()

import { Injectable } from '@nestjs/common';
import {
  HealthIndicatorResult,
  RegisterHealthCheck,
} from 'nest-healthkit';

@Injectable()
export class PaymentHealthIndicator {
  @RegisterHealthCheck('stripe')
  async checkStripe(): Promise<HealthIndicatorResult> {
    return {
      name: 'stripe',
      status: 'up',
      durationMs: 0,
    };
  }
}

Prototype methods are discovered automatically. Arrow-function class properties are not scanned because Nest's metadata scanner only walks the prototype.

Endpoints

| Method | Route | Description | Response | |---|---|---|---| | GET | /{path}/live | Process liveness check | { status, timestamp, uptime, checks } | | GET | /{path}/ready | Readiness check for all registered indicators | { status, timestamp, uptime, checks } | | GET | /{path} | Alias for readiness | { status, timestamp, uptime, checks } | | GET | /{path}/ui | Optional HTML dashboard | HTML when enabled, { error: 'Not found' } when disabled |

status: 'up' and status: 'degraded' return HTTP 200. status: 'down' returns HTTP 503.

Dashboard UI

Enable the dashboard with ui: true to serve a lightweight dark-mode HTML view at /{path}/ui. The page shows the overall status, uptime, timestamp, and a per-check table, and it auto-refreshes every 30 seconds.

Compatibility

| Concern | Requirement | |---|---| | NestJS version | ^9.0.0, ^10.0.0, and ^11.0.0 | | HTTP adapter | Express and Fastify | | TypeScript | ^5.0.0 | | Node.js | ^18.0.0 | | Prisma version | ^4.x and ^5.x | | TypeORM version | ^0.2.x and ^0.3.x | | ioredis version | ^4.x and ^5.x | | ESM/CJS | CJS output only |

Custom Indicators (advanced)

import { BaseIndicator, HealthCheckFn } from 'nest-healthkit';

class StripeIndicator extends BaseIndicator {
  getCheck(): HealthCheckFn {
    return async () =>
      this.measure('stripe', async () => {
        await Promise.resolve();
        return { region: 'us-east-1' };
      });
  }
}

Extend BaseIndicator when you want a reusable indicator with consistent duration measurement and error handling, then register the returned HealthCheckFn inside your own provider.