Skip to content

Services · Reference

Health Service

A configurable Effect service and HTTP API contract for aggregate, liveness, readiness, and startup checks.

Last updated October 8, 2026

Overview

service-health provides a configurable HealthService, documented Effect schemas, a HealthApiGroup, and an exported handler implementation. It exposes /health, /health/live, /health/ready, and /health/started. Successful checks return UP; any failed check produces DOWN, and the HTTP contract maps unhealthy responses to status 503. Package consumers import the complete public API from @krak-stack/registry/service-health.

Install

shell
bunx shadcn@latest add @krak-stack/service-health

Included Files

  • services/health/index.ts - public barrel and health service
  • services/health/schema.ts - health response schemas and HTTP status metadata
  • services/health/api.group.ts - public health API group
  • services/health/api.builder.ts - reusable handler implementation

Register The API Group

Add HealthApiGroup after applying authentication middleware to application groups so health endpoints remain public. Apply the root prefix after adding the health group so every endpoint receives the same prefix.

ts
import { HealthApiGroup } from "@/services/health";

export const Api = HttpApi.make("AppApi")
  .add(ApplicationApiGroup)
  .middleware(AuthMiddleware)
  .add(HealthApiGroup)
  .prefix("/api");

Build And Register The Handler

Bind the exported healthHandler implementation to the parent API group. Configure checks with HealthService.layerWith, then provide the resulting layer to the application's HttpApiBuilder layer. The handler automatically uses the paths and prefix already present on Api. Check dependencies such as DB are captured when the health service layer is built.

ts
import { Effect, Layer } from "effect";
import { HttpApiBuilder } from "effect/http-api";

import { Api } from "@/api";
import { DB } from "@/services/database";
import { healthHandler, HealthService } from "@/services/health";

const healthLayer = HttpApiBuilder.group(Api, "health", healthHandler).pipe(
  Layer.provide(
    HealthService.layerWith({
      checks: {
        ready: [
          {
            name: "database",
            check: Effect.gen(function* () {
              const db = yield* DB;
              yield* db.$client`SELECT 1`;
              return HealthService.up();
            }).pipe(Effect.timeout("2 seconds")),
          },
        ],
      },
    }),
  ),
);

export const apiLayer = HttpApiBuilder.layer(Api).pipe(
  Layer.provide(healthLayer),
  Layer.provide(DB.layer),
);

Failed effects, defects, and timeouts become DOWN results without exposing internal errors. Optional diagnostic data accepts non-sensitive string, number, and boolean values.

Dependencies
Packages and shadcn components required by this registry item.

Dependencies