@crossplatformai/health

Framework-agnostic health check function for Node.js applications.

This package provides a simple, consistent health check implementation that works across any Node.js runtime environment. It exposes a single createHealthStatus function that can be used directly in any HTTP framework (Hono, Express, Fastify, Next.js, etc.).

What this package provides

• createHealthStatus() - Pure function for generating health status with service name, version, and flexible metadata
• Simple, minimal API: just call the function with your configuration
• Type-safe interfaces with generic metadata support

Package boundary

This package owns:

• Health status generation logic
• Health configuration types
• Auto-generated timestamp in metadata

This package does not own:

• HTTP framework routing (mount /api/health in your app)
• Service lifecycle management
• Application-specific health checks (database connectivity, etc.)
• Authentication or authorization

Installation

pnpm add @crossplatformai/health

Usage

Basic usage with any framework

import { createHealthStatus } from '@crossplatformai/health';
import packageJson from './package.json';

// Get health status anywhere
const status = createHealthStatus({
  service: 'my-service',
  version: packageJson.version,
  metadata: {
    appEnv: process.env.APP_ENV,
    nodeEnv: process.env.NODE_ENV,
  },
});

// Returns:
// {
//   status: 'healthy',
//   service: 'my-service',
//   version: '1.0.0',
//   metadata: {
//     appEnv: 'development',
//     nodeEnv: 'production',
//     timestamp: '2026-03-18T10:15:30.000Z'
//   }
// }

With Hono

import { Hono } from 'hono';
import { createHealthStatus } from '@crossplatformai/health';

const app = new Hono();

app.get('/api/health', (c) => {
  const status = createHealthStatus({
    service: 'api-server',
    version: '1.0.0',
    metadata: {
      appEnv: 'production',
      nodeEnv: 'production',
    },
  });
  return c.json(status);
});

With Next.js

// app/api/health/route.ts
import { NextResponse } from 'next/server';
import { createHealthStatus } from '@crossplatformai/health';

export function GET() {
  const status = createHealthStatus({
    service: 'web',
    version: process.env.NEXT_PUBLIC_APP_VERSION ?? 'unknown',
    metadata: {
      appEnv: process.env.NEXT_PUBLIC_APP_ENV,
      nodeEnv: process.env.NODE_ENV,
    },
  });

  return NextResponse.json(status);
}

Import paths

• @crossplatformai/health - main export (createHealthStatus and types)

Configuration

HealthConfig

interface HealthConfig<
  TMetadata extends Record<string, unknown> = Record<string, unknown>,
> {
  service: string; // Required: Name of the service
  version: string; // Required: Version string
  metadata?: TMetadata; // Optional: Additional metadata (appEnv, nodeEnv, etc.)
}

HealthStatus

interface HealthStatus<
  TMetadata extends Record<string, unknown> = Record<string, unknown>,
> {
  status: 'healthy'; // Always 'healthy' (future: may support 'degraded')
  service: string; // Service name from config
  version: string; // Version from config
  metadata: TMetadata & {
    // Metadata from config + auto-generated timestamp
    timestamp: string; // ISO 8601 timestamp (auto-generated)
  };
}

Metadata

The metadata field accepts any JSON-serializable object. Common fields include:

• appEnv - Application environment (development, staging, production)
• nodeEnv - Node.js runtime mode (development, production)
• region - Deployment region (us-east-1, eu-west-1, etc.)
• buildId - CI/CD build identifier
• Any other custom fields your monitoring needs

Note: The module automatically adds/overwrites timestamp in metadata.

Runtime compatibility

This package uses standard JavaScript APIs and works in:

• Node.js: Full support
• Bun/Deno: Compatible
• Edge runtimes (Cloudflare Workers, etc.): Fully compatible

Publishing model

This package currently publishes raw TypeScript source.

That is intentional for now. Consuming repos are expected to use toolchains that can consume package TypeScript directly.

Testing

pnpm test
pnpm check-types
pnpm lint

License

See LICENSE.