Next.js

Creating a new Next.js status page? The starter sets up the page, API, database and local checks for you. Choose the Cloudflare or Vercel overlay if you need cron jobs in production. To add status to an existing App Router app, use the manual steps below; the page must render a fresh snapshot on each request.

Create a project

Pass next to select the template without a prompt. Omit flags to choose the framework, deployment, database and theme interactively.

bun create @heyo-sh/heyo-status my-status-page --template nextcd my-status-pagebun dev

If you skipped dependency installation in the creator, install the project's dependencies before starting it. Replace the example monitors in heyo-status.config.ts. For SQLite or Vercel/PostgreSQL, bun dev runs the local scheduler; bun run check runs one check without a global CLI install. Cloudflare/D1 uses Worker cron triggers instead and has no check script. For direct shell commands, see the CLI guide.

Add status to an existing app

The steps below add the page and API to an App Router app. You still need persistent storage and a production scheduler; the starter handles those platform-specific pieces for you.

1. Install and configure

Install the package in the app's root directory:

bun add @heyo-sh/heyo-status

You only need a global CLI install if you want to type heyo-status … directly in your shell.

Create heyo-status.config.ts at the project root. This SQLite example needs a persistent filesystem; for Vercel use PostgreSQL, and for Cloudflare use D1 and the generated Worker overlay.

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",  monitors: [{ name: "Website", type: "http", url: "https://acme.com" }],});export default statusPage;

To test a monitor before scheduling it, install the global CLI and run heyo-status check run from the project root. It reads the config and database without a running Next.js server (and requires Bun 1.4.3+). For Cloudflare/D1, use Worker cron triggers instead; a local shell has no D1 binding.

2. Mount the API

Mount the catch-all handler at the default basePath, /api/heyo-status. A dynamic import keeps embedded SQLite out of Next's build-time static analysis.

import { statusHandler } from "@heyo-sh/heyo-status/next";async function handle(method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE", request: Request) {  const { statusPage } = await import("../../../../heyo-status.config");  return statusHandler(statusPage)[method](request);}export const GET = (request: Request) => handle("GET", request);export const POST = (request: Request) => handle("POST", request);export const PATCH = (request: Request) => handle("PATCH", request);export const PUT = (request: Request) => handle("PUT", request);export const DELETE = (request: Request) => handle("DELETE", request);

3. Render a fresh snapshot

Import the theme stylesheet in app/layout.tsx. Render the head bootstrap script there as in the generated layout when using light/dark mode.

import "@heyo-sh/heyo-status/theme/status.css";export default function RootLayout({ children }: { children: React.ReactNode }) {  return <html lang="en"><body>{children}</body></html>;}

import { StatusPage } from "@heyo-sh/heyo-status/ui";export const dynamic = "force-dynamic";export default async function Page() {  const { statusPage } = await import("../heyo-status.config");  const snapshot = await statusPage.api.getSnapshot();  return <StatusPage snapshot={snapshot} theme={statusPage.theme} title={statusPage.title} />;}

Pass branding, colors, mode, basePath, metrics and subscriber settings as well if configured. force-dynamic is essential: without it, Next.js can serve a snapshot from build time instead of the latest checks.

4. Schedule checks

statusPage.cron exposes runChecks, summarize and cleanup. The manual integration needs a scheduler to call them; a route alone does not run checks. For a production deployment, use the generated Vercel cron routes or Cloudflare Worker triggers. On your own server, run one scheduler.