Health Check

The Health Check component provides production-ready endpoints for monitoring your API's status, system health, and service availability. Essential for load balancers, monitoring systems, and deployment tools.

Features

Basic health check - Simple endpoint to verify service is running
Detailed health check - System information including memory, CPU, and uptime
Database connectivity check - Optional database health verification
Customizable - Easy to extend with additional health checks
Production-ready - Standardized responses for monitoring tools

Installation Guide

This component requires additional Servercn components.

👉 You do not need to install any Servercn components manually. Running this component installer will automatically install all required components. Manual installation is optional and only recommended if you prefer fine-grained components control

1. Install Servercn components(Optional)

2. Install this component

npx servercn-cli add health-check

Basic Implementation

1. MVC Structure

Create health check controller in src/controllers/health.controller.ts:

import { Request, Response } from "express";
import { ApiResponse } from "../utils/api-response";
 
export const healthCheck = async (_req: Request, res: Response) => {
  return ApiResponse.Success(res, "Service is healthy", {
    status: "healthy",
    timestamp: new Date().toISOString(),
    uptime: process.uptime()
  });
};

Create routes in src/routes/health.routes.ts:

import { Router } from "express";
import { healthCheck } from "../controllers/health.controller";
 
const router = Router();
 
router.get("/", healthCheck);
 
export default router;

2. Feature Structure

For feature-based architecture, place controller in src/modules/health/health.controller.ts:

import { Request, Response } from "express";
import { ApiResponse } from "../../shared/utils/api-response";
 
export const healthCheck = async (_req: Request, res: Response) => {
  return ApiResponse.Success(res, "Service is healthy", {
    status: "healthy",
    timestamp: new Date().toISOString(),
    uptime: process.uptime()
  });
};

Usage Examples

1. Basic Health Check

Simple endpoint that returns service status:

import { ApiResponse } from "../utils/api-response";
 
export const healthCheck = async (_req: Request, res: Response) => {
  return ApiResponse.Success(res, "Service is healthy", {
    status: "healthy",
    timestamp: new Date().toISOString(),
    uptime: process.uptime()
  });
};

Response:

{
  "success": true,
  "message": "Service is healthy",
  "statusCode": 200,
  "data": {
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "uptime": 3600.5
  }
}

2. Detailed Health Check

Include system information:

import { ApiResponse } from "../utils/api-response";
 
export const detailedHealthCheck = async (_req: Request, res: Response) => {
  const healthData = {
    status: "healthy",
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
    environment: process.env.NODE_ENV || "development",
    version: process.env.npm_package_version || "1.0.0",
    memory: {
      used:
        Math.round((process.memoryUsage().heapUsed / 1024 / 1024) * 100) / 100,
      total:
        Math.round((process.memoryUsage().heapTotal / 1024 / 1024) * 100) / 100,
      unit: "MB"
    },
    cpu: {
      usage: process.cpuUsage()
    }
  };
 
  return ApiResponse.Success(res, "Service is healthy", healthData);
};

Response:

{
  "success": true,
  "message": "Service is healthy",
  "statusCode": 200,
  "data": {
    "status": "healthy",
    "timestamp": "2026-01-09T14:15:21.360Z",
    "uptime": 155.729376,
    "environment": "development",
    "version": "1.0.0",
    "memory": {
      "used": 41.59,
      "total": 44.46,
      "unit": "MB"
    },
    "cpu": {
      "usage": {
        "user": 3031000,
        "system": 812000
      }
    }
  }
}

Route Setup

src/routes/health.routes.ts

import { Router } from "express";
import {
  healthCheck,
  detailedHealthCheck,
  healthCheckWithDB
} from "../controllers/health.controller";
 
const router = Router();
 
router.get("/", healthCheck);
router.get("/detailed", detailedHealthCheck);
router.get("/db", healthCheckWithDB);
 
export default router;

src/app.ts

import express, { type Application } from "express";
import healthRoutes from "./routes/health.routes";
 
const app: Application = express();
 
app.use(express.json());
 
// Health check routes (usually placed early)
app.use("/api/health", healthRoutes);
 
// Other routes...

Security Considerations

Rate limiting - Consider rate limiting health check endpoints
Authentication - Optionally protect detailed endpoints
IP whitelisting - Restrict access to monitoring IPs if needed
Information disclosure - Don't expose sensitive system information

Common Use Cases

Load balancer health checks - Verify service availability
Monitoring systems - Track service uptime and performance
Deployment verification - Confirm successful deployments
Auto-scaling - Determine when to scale services
Incident response - Quick status verification during outages