@growth-labs/health

Lightweight health check route for uptime monitoring. Checks D1, KV, and R2 connectivity.

Config

import health from '@growth-labs/health'

health({
  d1Bindings: ['SITE_DB'],                      // D1 databases to check (SELECT 1)
  kvBindings: ['SITE_KV'],                      // KV namespaces to check (read canary key)
  r2Bindings: ['MEDIA_BUCKET'],                 // R2 buckets to check (read canary object)
  kvCanaryKey: '_health_canary',                 // Key to read (must be pre-placed)
  kvCanaryValue: 'ok',                           // Expected value
  r2CanaryKey: 'health-check.txt',               // Object to read (must be pre-placed)
  routePath: '/api/health',
  bearerToken: '...',                            // Optional: require auth for health endpoint
  checkTimeout: 5000,                            // Per-check timeout (ms)
  checks: [                                      // Optional custom checks (function references)
    { name: 'external-api', check: async (env) => { ... } },
  ],
})

What It Injects

Route: GET /api/health — returns { ok: true/false, checks: [...], timing: ... }

No middleware. No overhead on non-health requests.

Canary Setup (One-Time)

# KV canary
wrangler kv:key put --binding SITE_KV "_health_canary" "ok"

# R2 canary
echo "ok" | wrangler r2 object put MEDIA_BUCKET/health-check.txt --pipe

Package does NOT create canaries — health checks verify infrastructure state, not create it.

Response Format

{
  "ok": true,
  "checks": [
    { "name": "d1:SITE_DB", "ok": true, "ms": 3 },
    { "name": "kv:SITE_KV", "ok": true, "ms": 1 },
    { "name": "r2:MEDIA_BUCKET", "ok": true, "ms": 5 }
  ],
  "totalMs": 8
}

Key Patterns

• Virtual module: virtual:growth-labs/health/config
• Custom checks use module-level registry (function refs can't serialize through virtual module)
• No auth, no analytics write on health endpoint
• Bearer token optional for public vs private health checks