Quickstart

The generator creates a framework template, a database adapter and a deployment overlay, then prints the commands to run the project. It needs Bun 1.4.3+ to be installed even if you choose another package manager, because the generated CLI and dev scripts run with Bun.

1. 1

   Create the project

   Run the creator and answer the prompts: framework, theme, deployment target, database and package manager.

   Option 1Option 2Option 3Option 4

   Copy

   pnpm create @heyo-sh/heyo-status

   To skip the prompts entirely, pass flags:

   bashCopy

   bun create @heyo-sh/heyo-status my-status-page \  --template react-router \  --theme slate \  --deployment later \  --database sqlite \  --package-manager bun

2. 2

   Configure the environment

   Copy the example file and fill in the secrets your target needs.

   bashCopy

   cd my-status-pagecp .env.example .env

   .envCopy

   # Local SQLite file. Use an absolute path in production.HEYO_STATUS_DB_PATH=status.sqlite# Bearer token for /api/heyo-status/admin/*. Without it, writes stay closed.HEYO_STATUS_API_TOKEN=replace-me# Vercel cron routes only.# CRON_SECRET=replace-me# PostgreSQL deployments only.# DATABASE_URL=postgres://user:password@host/database

3. 3

   Run it

   dev starts the framework dev server and the local cron scheduler together, and performs one check immediately so the page is never empty.

   bashCopy

   bun dev

   Optionally seed 90 days of history so the uptime bars have something to draw before the scheduler has run for a day:

   bashCopy

   bun run db:seed

4. 4

   Replace the example monitors

   The starter ships grouped HTTP checks, a DNS check and a composite monitor, all pointing at example.com. Edit heyo-status.config.ts and point them at your own services before publishing anything.

Add it to an existing application

bun add @heyo-sh/heyo-status

1. 1

   Declare the page

   Create heyo-status.config.ts in the project root. The CLI and every documented example load it from exactly that path.

   heyo-status.config.tsCopy

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

2. 2

   Mount one catch-all route

   Every endpoint is served beneath basePath, which defaults to /api/heyo-status.

   Option 1Option 2Option 3

   Copy

   // app/api/heyo-status/[...path]/route.tsimport { statusHandler } from "@heyo-sh/heyo-status/next";import { statusPage } from "../../../../heyo-status.config";export const { GET, POST, PATCH, PUT, DELETE } = statusHandler(statusPage);

3. 3

   Render the page

   Import the stylesheet once in the root layout, then pass a snapshot to <StatusPage />.

   tsxCopy

   import { StatusPage } from "@heyo-sh/heyo-status/ui";import "@heyo-sh/heyo-status/theme/status.css";import { statusPage } from "../heyo-status.config";const snapshot = await statusPage.api.getSnapshot();<StatusPage  basePath={statusPage.basePath}  branding={statusPage.branding}  metrics={statusPage.metrics}  mode={statusPage.mode}  snapshot={snapshot}  theme={statusPage.theme}  title={statusPage.title}/>;

4. 4

   Schedule the checks

   Nothing runs itself. Locally, heyo-status dev owns the schedule. In production, use the platform's cron: Cloudflare triggers, Vercel Cron, or node-cron when self-hosting.

   bashCopy

   heyo-status dev -- next dev

Verify the install

# Run every configured monitor once and store the results.heyo-status check run# Apply migrations where the adapter supports them.heyo-status db migrate# Fabricate 90 days of history at 99.95% uptime.heyo-status db seed --uptime 99.95 --days 90

Then read the API back:

curl http://localhost:3000/api/heyo-status/status/summarycurl http://localhost:3000/api/heyo-status/healthz