@actsasgeek/healthcheck

Dead-simple health check endpoint for Next.js apps with Supabase.

Part of ActsAsGeek - Uptime monitoring for developers.

Installation

npm install @actsasgeek/healthcheck

Quick Start (30 seconds)

1. Add your monitor key to .env.local

ACTSASGEEK_MONITOR_KEY=aag_your-project-id_your-secret

Get this key from your ActsAsGeek dashboard.

2. Create the route

// app/healthcheck/route.ts
export { GET } from '@actsasgeek/healthcheck/nextjs'

Done! Your /healthcheck endpoint is now ready.

What It Does

• Validates requests from ActsAsGeek using your monitor key or trusted agent detection
• Auto-detects Supabase from your existing environment variables
• Returns detailed health info for authenticated requests
• Returns minimal info for unauthenticated requests (safe for public)
• Trusted agent support - ActsAsGeek monitoring agents bypass signature verification

Response Format

Authenticated:

{
  "status": "healthy",
  "service": "your-app",
  "checks": {
    "api": { "status": "pass" },
    "database": { "status": "pass", "responseTime": 45 }
  }
}

Unauthenticated:

{
  "status": "online",
  "service": "your-app"
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | ACTSASGEEK_MONITOR_KEY | Yes | Your monitor key from ActsAsGeek | | NEXT_PUBLIC_SUPABASE_URL | No | Auto-detected for database checks | | NEXT_PUBLIC_SUPABASE_ANON_KEY | No | Auto-detected for database checks | | SERVICE_NAME | No | Override service name in responses | | HEALTHCHECK_LOG_PINGS | No | Set to true to log pings to database | | HEALTHCHECK_TRUSTED_AGENTS | No | Additional trusted agent patterns (comma-separated) |

Trusted Agents

The package recognizes ActsAsGeek monitoring agents by their User-Agent header and allows them to access full health check details without signature verification.

Default trusted agents:

• VibeOps-Uptime-Monitor - ActsAsGeek's primary monitoring agent
• ActsAsGeek - Any request with ActsAsGeek in the User-Agent

Request behavior by source:

| Request Source | Auth Required | Full Health Data | |----------------|---------------|------------------| | VibeOps-Uptime-Monitor/1.0 | No | Yes | | ActsAsGeek/* | No | Yes | | Signed request (any source) | Yes (verified) | Yes | | Other (browser, curl, etc.) | N/A | No (minimal) |

Adding custom trusted agents:

HEALTHCHECK_TRUSTED_AGENTS=MyMonitor,CustomAgent

This allows you to whitelist additional monitoring services that should receive full health check data.

Ping Logging

Enable HEALTHCHECK_LOG_PINGS=true to record each healthcheck request in your database. This creates an audit trail of monitoring activity on your side.

Create the table in your Supabase project:

create table healthcheck_pings (
  id uuid primary key default gen_random_uuid(),
  service text not null,
  domain text,
  source_ip text,
  user_agent text,
  status text not null,
  checks_run text[] default '{}',
  created_at timestamptz default now()
);

create index healthcheck_pings_created_at_idx on healthcheck_pings(created_at desc);

License

MIT