@nestjs/terminus

What is @nestjs/terminus?

@nestjs/terminus is a health check module for NestJS applications. It provides a way to monitor the health of your application by exposing various health indicators and endpoints. This can be useful for ensuring that your application is running smoothly and for integrating with monitoring tools.

What are @nestjs/terminus's main functionalities?

Basic Health Check

This code sets up a basic health check endpoint in a NestJS application. The `HealthCheckService` is used to perform the health check, and the `@HealthCheck` decorator is used to mark the endpoint.

```typescript
import { Module } from '@nestjs/common';
import { TerminusModule } from '@nestjs/terminus';
import { HealthController } from './health.controller';

@Module({
  imports: [TerminusModule],
  controllers: [HealthController],
})
export class AppModule {}

import { Controller, Get } from '@nestjs/common';
import { HealthCheck, HealthCheckService } from '@nestjs/terminus';

@Controller('health')
export class HealthController {
  constructor(private health: HealthCheckService) {}

  @Get()
  @HealthCheck()
  check() {
    return this.health.check([]);
  }
}
```

Database Health Check

This code adds a database health check to the health endpoint. The `TypeOrmHealthIndicator` is used to check the health of the database connection.

```typescript
import { TypeOrmHealthIndicator, HealthCheckService, HealthCheck } from '@nestjs/terminus';
import { Controller, Get } from '@nestjs/common';

@Controller('health')
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private db: TypeOrmHealthIndicator,
  ) {}

  @Get()
  @HealthCheck()
  check() {
    return this.health.check([
      async () => this.db.pingCheck('database'),
    ]);
  }
}
```

Custom Health Indicator

This code demonstrates how to create a custom health indicator. The `CustomHealthIndicator` class extends `HealthIndicator` and implements the `isHealthy` method. This custom indicator is then used in the health check endpoint.

```typescript
import { HealthIndicator, HealthIndicatorResult, HealthCheckError } from '@nestjs/terminus';
import { Injectable } from '@nestjs/common';

@Injectable()
export class CustomHealthIndicator extends HealthIndicator {
  async isHealthy(key: string): Promise<HealthIndicatorResult> {
    const isHealthy = true; // Custom logic to determine health
    const result = this.getStatus(key, isHealthy);
    if (isHealthy) {
      return result;
    }
    throw new HealthCheckError('Custom health check failed', result);
  }
}

import { Controller, Get } from '@nestjs/common';
import { HealthCheck, HealthCheckService } from '@nestjs/terminus';

@Controller('health')
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private customHealthIndicator: CustomHealthIndicator,
  ) {}

  @Get()
  @HealthCheck()
  check() {
    return this.health.check([
      async () => this.customHealthIndicator.isHealthy('custom'),
    ]);
  }
}
```

Other packages similar to @nestjs/terminus

express-healthcheck

express-healthcheck is a middleware for Express.js applications that provides a simple health check endpoint. It is less feature-rich compared to @nestjs/terminus but can be a good choice for simpler use cases.

node-health-check

node-health-check is a lightweight health check library for Node.js applications. It provides basic health check functionality and can be easily integrated into any Node.js application. It is not as tightly integrated with a specific framework like @nestjs/terminus is with NestJS.

healthcheck-middleware

healthcheck-middleware is another middleware option for adding health checks to Node.js applications. It is framework-agnostic and provides a simple way to add health check endpoints. It lacks the advanced features and integrations of @nestjs/terminus.

README

A progressive Node.js framework for building efficient and scalable server-side applications, heavily inspired by Angular.

Description

This module contains integrated healthchecks for Nest.

Installation

@nestjs/terminus integrates with a lot of cool technologies, such as typeorm, grpc, mongodb, and many more! In case you have missed a dependency, @nestjs/terminus will throw an error and prompt you to install the required dependency. So you will only install what is actually required!

npm install --save @nestjs/terminus

Usage

• Import the Terminus module
• Make sure the additionally needed modules are available to (e.g. TypeOrmModule), in case you want to do Database Health Checks.

// app.module.ts

@Module({
  controllers: [HealthController],
  imports:[
    // Make sure TypeOrmModule is available in the module context
    TypeOrmModule.forRoot({ ... }),
    TerminusModule
  ],
})
export class HealthModule { }

• Setup your HealthController which executes your Health Check.

// health.controller.ts

@Controller('health')
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private db: TypeOrmHealthIndicator,
  ) {}

  @Get()
  @HealthCheck()
  readiness() {
    return this.health.check([
      async () => this.db.pingCheck('database', { timeout: 300 }),
    ]);
  }
}

If everything is set up correctly, you can access the healthcheck on http://localhost:3000/health.

{
  "status": "ok",
  "info": {
    "database": {
      "status": "up"
    }
  },
  "details": {
    "database": {
      "status": "up"
    }
  }
}

For more information, see docs. You can find more samples in the samples/ folder of this repository.

Contribute

In order to get started, first read through our Contributing guidelines.

Setup

Setup the development environment by following these instructions:

• Fork & Clone the repository
• Install the dependencies

pnpm i
pnpm dev

In order to test the library against a sample, simply go to a sample and run pnpm start:dev

cd sample/000-dogs-app
pnpm start:dev

[!NOTE] Once the library is rebuilt, the pnpm start:dev within a sample needs to be restarted in order to pick up the changes.

Test

For unit testing run the following command:

pnpm test

For e2e testing, a Docker Compose stack is required. Make sure Docker is installed on your machine and run the following command.

docker compose up -d
pnpm test:e2e

Support

Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please read more here.

Stay in touch

• Author - Kamil Myśliwiec and Livio Brunner
• Website - https://nestjs.com
• Twitter - @nestframework

License

Nest is MIT licensed.

Changelog

11.0.0-beta.1 (2025-01-25)

Bug Fixes

• deps: update dependency @grpc/proto-loader to v0.7.13 (bf08ece)
• deps: update dependency @nestjs/typeorm to v10.0.2 (8430d1f)
• deps: update dependency mysql2 to v3.9.8 [security] (eae8679)
• deps: update dependency reflect-metadata to v0.2.2 (004d971)

Features

• update dependencies (969bfd7)