Fastify Actuator

A lightweight Fastify plugin that adds a customizable health check and env endpoint to your Fastify applications. Inspired by Spring Boot's actuator endpoints, this plugin provides a simple way to monitor your application.

Features

• 🚀 Simple health check and env endpoint
• ⚙️ Customizable endpoint prefix
• 📦 Written in TypeScript
• 🔌 Easy to integrate with Fastify applications

Installation

npm install fastify-actuator

Usage

Example: Health and Env Endpoints

import fastify from 'fastify';
import { healthCheck, envEndpoint } from 'fastify-actuator';

const app = fastify();

// Register the health check endpoint
app.register(healthCheck);

// Register the env endpoint
app.register(envEndpoint);

// Or use custom prefixes/settings
// app.register(healthCheck, { prefix: '/custom-health' });
// app.register(envEndpoint, { prefix: '/custom-env', settings: './settings.ts' });

app.listen({ port: 3000 });

The endpoints will be available at:

• Health: GET /actuator/health
• Env: GET /actuator/env

Example responses:

Health

{
  "status": "up"
}

Env

{
  "PORT": "3000",
  "NODE_ENV": "development",
  "API_KEY": "your-api-key-here",
  "ENABLE_FEATURE_X": "false"
}

multiRegister

multiRegister is a utility function that allows you to register multiple Fastify actuator plugins at once, applying the same options to all of them. This is useful for grouping endpoints under a common prefix or sharing configuration.

Example: Using multiRegister

import fastify from 'fastify';
import { healthCheck, envEndpoint, multiRegister } from 'fastify-actuator';

const app = fastify();

// Register both endpoints under a custom prefix and shared options
app.register(
  multiRegister([healthCheck, envEndpoint]),
  { prefix: '/custom', settings: ['./settings.ts', '.env'] }
);

app.listen({ port: 3000 });

This will expose:

• Health: GET /custom/health
• Env: GET /custom/env

Options

| Option | Type | Default | Description | Endpoint | |----------|------------------|------------------------------|--------------------------------------------------------------------|--------------| | prefix | string | '/actuator' | Custom prefix for the endpoint | health, env | | settings | string|string[] | ['./settings.ts', '.env'] | Path(s) to settings file(s) for default env values (TypeScript/JS) | env |

Environment Configuration

This plugin can read environment variables from both a .env file and a TypeScript settings.ts file. The settings.ts file allows you to define default values and types for your environment variables, while the .env file can override these defaults at runtime.

Sample .env

PORT=3000
NODE_ENV=development
API_KEY=your-api-key-here

Sample settings.ts

export default {
  PORT: Number({ default: 8080 }),
  NODE_ENV: String({ default: 'production' }),
  API_KEY: String({ default: '' }),
  ENABLE_FEATURE_X: Boolean({ default: false })
};

• The plugin will merge values from settings.ts and .env, with .env taking precedence.
• You can specify a custom location for settings.ts and .env file via the settings option.

Changelog

1.1.2

• Fixed a bug that caused endpoints to be registered with a duplicated prefix (e.g., /actuator/actuator/health). Endpoints now correctly use the configured prefix without duplication.

1.1.0

• Added envEndpoint for /env endpoint to expose merged environment and settings values.
• Updated options table, with accurate defaults.
• Improved usage examples for health and env endpoints.
• Fixed 1 low-severity vulnerability

1.0.0

• Initial release with health check endpoint (/actuator/health).

Migration Guide: 1.0.0 → 1.1.0

• New Env Endpoint:

  • To use the new /env endpoint, import and register envEndpoint from fastify-actuator:

    import { envEndpoint } from 'fastify-actuator';
    app.register(envEndpoint);

  • You can customize the prefix and settings file(s) as shown in the updated usage example.

• Updated Imports:

  • If you previously used the default import for health check, switch to named import:

    import { healthCheck } from 'fastify-actuator';

• Options Table:

  • Review the new options table for updated defaults and descriptions.

• No Breaking Changes:

  • Existing health check usage will continue to work, but updating imports and reviewing new features is recommended.

License

ISC