Configuration file

Every setting accepted by heyoStatus(), its default and where it is read.

heyo-status.config.ts in the project root is the single source of truth. The CLI loads it from that path, the framework routes import it, the deployment overlays reference it, and the scheduler reads its cron expressions. Keep one file; do not maintain a second configuration for the build.

heyo-status.config.ts

import { heyoStatus } from "@heyo-sh/heyo-status/config";import { sqlite } from "@heyo-sh/heyo-status/db";export const statusPage = heyoStatus({  database: sqlite("status.sqlite"),  title: "Acme Status",  description: "Real-time status for Acme services.",  siteUrl: "https://status.acme.com",  theme: "slate",  monitors: [{ name: "Website", type: "http", url: "https://acme.com" }],  adminToken: process.env.HEYO_STATUS_API_TOKEN,});export default statusPage;

heyoStatus() validates the object as the module loads, applies defaults and returns a StatusPage. Misspelled keys and wrongly shaped values throw immediately rather than being silently ignored — every section of the schema is strict().

Export it as default or as `statusPage`

The CLI accepts either. Generated templates export both so that import { statusPage } and heyo-status check run work from the same file.

Top-level settings

Setting	Type	Default	Purpose
`database`	`StatusDatabaseAdapter`	required	Persistence. SQLite, D1, PostgreSQL or your own implementation.
`title`	`string`	`"Heyo Status"`	Metadata, feed and notification name. Not header text.
`description`	`string`	`"Real-time service status and uptime."`	Page and feed description.
`siteUrl`	`string`	—	Canonical HTTP(S) base URL. No query string or fragment.
`basePath`	`string`	`"/api/heyo-status"`	Mount point of the catch-all route; stripped before routing.
`adminToken`	`string`	`HEYO_STATUS_API_TOKEN`	Bearer token for `/admin/*`.
`theme`	`"slate" \| "fern" \| "onyx" \| "dune" \| "reed"`	`"slate"`	Bundled layout and its tokens.
`colors`	`{ primary?, secondary? }`	`{}`	CSS colour overrides applied as tokens.
`mode`	`"system" \| "light" \| "dark"`	`"system"`	Initial colour mode.
`branding`	`{ name?, logo? }`	`{}`	Header logo and optional label beside it.
`monitors`	`StatusMonitorConfig[]`	`[]`	What to check. Names must be unique.
`checks`	`object`	see below	Schedule, retention and the displayed window.
`notifications`	`object`	see below	Failure threshold and channels.
`incidents`	`{ enabled }`	`{ enabled: true }`	Incident API, feeds and automatic incidents.
`maintenance`	`{ enabled }`	`{ enabled: true }`	Maintenance API and alert suppression.
`metrics`	`object`	see below	What the UI shows, plus badges and Prometheus.
`subscribers`	`object`	`{ enabled: false, … }`	Public subscriptions.
`cache`	`{ snapshotTtlMs }`	`{ snapshotTtlMs: 30000 }`	In-process snapshot cache lifetime.
`telemetry`	`boolean \| { enabled, endpoint }`	enabled	Anonymous adoption ping.

Nested defaults

Each nested object is merged with its defaults, so you only set what differs.

checksStatusChecksConfigoptional

interval "*/5 * * * *" · retentionDays 90 · displayDays 90 · summaryCron "10 0 * * *" · cleanupCron "0 3 * * *". displayDays may not exceed retentionDays. See Checks and scheduling.

notificationsStatusNotificationsConfigoptional

failureThreshold 3 · channels []. Channel ids must be unique. See Notifications.

metricsStatusMetricsConfigoptional

showLatency true · showLatencyChart true · showUptimePercent true · uptimePeriods ["24h","7d","30d","90d"] · badges true · prometheus false. See Metrics and badges.

subscribersStatusSubscribersConfigoptional

enabled false · methods ["email","rss"] · requireConfirmation true. webhook is never enabled implicitly. See Subscribers.

cacheStatusCacheConfigoptional

snapshotTtlMs 30000, between 0 (disabled) and 3600000.

telemetryboolean | StatusTelemetryConfigoptional

enabled true · endpoint "https://telemetry.heyo.sh/v1/status". See Telemetry.

A complete example

heyo-status.config.ts

import { heyoStatus } from "@heyo-sh/heyo-status/config";import { sqlite } from "@heyo-sh/heyo-status/db";import { slack, webhook } from "@heyo-sh/heyo-status/notifications";export const statusPage = heyoStatus({  database: sqlite(process.env.HEYO_STATUS_DB_PATH ?? "status.sqlite"),  title: "Acme Status",  description: "Real-time status for Acme services.",  siteUrl: "https://status.acme.com",  basePath: "/api/heyo-status",  adminToken: process.env.HEYO_STATUS_API_TOKEN,  theme: "slate",  mode: "system",  colors: { primary: "#0f172a" },  branding: { logo: "/logo.svg", name: "Acme" },  monitors: [    { name: "Website", group: "Web", type: "http", url: "https://acme.com" },    { name: "API", group: "API", type: "http", url: "https://api.acme.com/health" },    { name: "DNS", group: "Infrastructure", type: "dns", host: "acme.com" },    { name: "Platform", type: "composite", monitors: ["Website", "API"], strategy: "all" },  ],  checks: {    interval: "*/5 * * * *",    retentionDays: 90,    displayDays: 90,    summaryCron: "10 0 * * *",    cleanupCron: "0 3 * * *",  },  notifications: {    failureThreshold: 3,    channels: [      slack({ webhookUrl: process.env.SLACK_WEBHOOK_URL!, events: ["monitor.*", "incident.*"] }),      webhook({ url: "https://ops.acme.com/hooks/status", secret: process.env.HOOK_SECRET! }),    ],  },  incidents: { enabled: true },  maintenance: { enabled: true },  metrics: { badges: true, prometheus: true, uptimePeriods: ["24h", "30d"] },  subscribers: { enabled: true, methods: ["email", "rss"], requireConfirmation: true },  cache: { snapshotTtlMs: 30_000 },  telemetry: false,});export default statusPage;

What `heyoStatus()` returns

The returned object is the validated configuration with three non-enumerable runtime properties attached, so it still serialises cleanly:

handler(request: Request) => Promise<Response>optional

The whole HTTP surface. It strips basePath from the incoming URL, so one catch-all route serves every endpoint.

apiStatusPageApioptional

getSnapshot(now?), listMonitors(now?), getMonitor(name, now?) and invalidate(). Reads share the snapshot cache with the HTTP routes.

cronStatusPageCronoptional

runChecks(now?), summarize(now?) and cleanup(now?) — the three jobs a scheduler calls.

const snapshot = await statusPage.api.getSnapshot();const api = await statusPage.api.getMonitor("API");await statusPage.cron.runChecks();

Environment variables

Variable	Read by	Purpose
`HEYO_STATUS_API_TOKEN`	`/admin/*` middleware	Fallback admin bearer token.
`HEYO_STATUS_CONFIG`	CLI	Default configuration path.
`HEYO_STATUS_DB_PATH`	generated SQLite adapter	SQLite file location.
`DATABASE_URL`	generated PostgreSQL adapter	PostgreSQL connection string.
`CRON_SECRET`	`vercelCronHandler`	Bearer secret for Vercel cron routes.
`HEYO_TELEMETRY_DISABLED`	telemetry	Opt out of the anonymous ping.
`DO_NOT_TRACK`, `CI`	telemetry	Also disable telemetry.
`PORT`	`heyo-status dev` standalone server	Port when no framework command is passed.

Validation rules that surprise people

basePath must start with /, must not be "/", must not contain //, a query string or a fragment. Trailing slashes are trimmed.
siteUrl must be HTTP(S) with no query string or fragment. A trailing slash is removed.
checks.displayDays cannot exceed checks.retentionDays: the page cannot display history the cleanup job has already deleted.
Monitor names must be unique, and a composite monitor may only reference monitors that actually perform a check.
notifications.channels cannot contain two channels with the same id.
metrics.uptimePeriods and subscribers.methods cannot contain duplicates.