Recipes

# Kill switches in Next.js

Read validated config in Next.js server components, with a timeout and defaults, and refresh it the moment you publish.

Turn on maintenance mode, show a banner or switch off a broken feature on a Next.js site without a redeploy. This recipe reads a hotcfg bin in server components, caches it with Next.js's `fetch`, falls back to defaults if hotcfg can't be reached, and, on Pro, refreshes the cache the moment you publish. It uses the App Router.

## The config

site-flags.json

```
{
  "maintenance": false,
  "banner": null,
  "features": { "new_checkout": false }
}
```

A schema keeps a typo from taking the site down:

schema.json

```
{
  "type": "object",
  "required": ["maintenance", "features"],
  "properties": {
    "maintenance": { "type": "boolean" },
    "banner": { "type": ["string", "null"], "maxLength": 200 },
    "features": { "type": "object", "additionalProperties": { "type": "boolean" } }
  }
}
```

terminal

```
hotcfg bins create site-flags --schema schema.json --public
hotcfg push site-flags.json --bin site-flags --env production
hotcfg types --bin acme/site-flags --lang typescript -o lib/site-flags.ts
```

The last command writes the `SiteFlags` type from the schema. Run it again when the schema changes, and the build fails where the code reads a key that's gone. See [hotcfg types](https://hotcfg.run/docs/cli/types).

## Reading the flags

lib/flags.ts

```
import { cache } from "react";
import type { SiteFlags } from "./site-flags";

const URL = "https://api.hotcfg.run/v1/acme/site-flags";
const DEFAULTS: SiteFlags = { maintenance: false, banner: null, features: {} };

// cache(): one fetch per render, however many components ask.
export const getFlags = cache(async (): Promise<SiteFlags> => {
  try {
    const res = await fetch(URL, {
      cache: "force-cache",
      next: { revalidate: 300, tags: ["hotcfg"] }, // refetched at most every 5 minutes, or on the webhook below
      signal: AbortSignal.timeout(2000), // never hold up a page for more than 2 seconds
    });
    if (!res.ok) return DEFAULTS;
    return { ...DEFAULTS, ...((await res.json()) as SiteFlags) };
  } catch {
    return DEFAULTS; // timed out or unreachable: render with the defaults
  }
});
```

Use it in any server component, layout or route handler:

app/layout.tsx

```
import { getFlags } from "@/lib/flags";
import { Maintenance } from "@/components/maintenance";

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const flags = await getFlags();
  return (
    <html lang="en">
      <body>
        {flags.banner && <div role="status">{flags.banner}</div>}
        {flags.maintenance ? <Maintenance /> : children}
      </body>
    </html>
  );
}
```

app/checkout/page.tsx

```
import { getFlags } from "@/lib/flags";

export default async function Checkout() {
  const { features } = await getFlags();
  return features.new_checkout ? <NewCheckout /> : <OldCheckout />;
}
```

Within the five minutes, Next.js answers from its own cache without asking hotcfg. When it does ask, hotcfg answers from Cloudflare's edge, and keeps answering for up to a week if its servers are down, so the defaults are a last resort. To pass flags to client components, read them in a server component and pass them as props.

## Refreshing on publish

On Pro, a [webhook](https://hotcfg.run/docs/guides/webhooks) tells your site when the bin changes, so a flip shows up at once instead of within five minutes. Add a route handler that checks the signature and expires the `hotcfg` tag:

app/api/hotcfg/route.ts

```
import { createHmac, timingSafeEqual } from "node:crypto";
import { revalidateTag } from "next/cache";

const CHANGES = new Set(["publish", "promote", "rollback", "unpublish", "rollout"]);

export async function POST(req: Request) {
  const body = await req.text(); // the exact bytes hotcfg signed
  if (!verifyHotcfg(body, req.headers.get("x-hotcfg-signature"), process.env.HOTCFG_WEBHOOK_SECRET ?? "")) {
    return new Response("bad signature", { status: 401 });
  }
  const event = JSON.parse(body) as { event: string; environment: string };
  if (CHANGES.has(event.event) && event.environment === "production") {
    revalidateTag("hotcfg", { expire: 0 }); // the next request fetches the new config
  }
  return new Response(null, { status: 204 });
}

// From "Check the signature" in the webhooks guide.
function verifyHotcfg(rawBody: string, header: string | null, secret: string): boolean {
  const fields = (header ?? "").split(",").map((f) => f.trim().split("="));
  const t = fields.find(([k]) => k === "t")?.[1] ?? "";
  const signatures = fields.filter(([k]) => k === "v1").map(([, v]) => v ?? "");
  if (!secret || !/^\d+$/.test(t) || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = Buffer.from(createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"));
  return signatures.some((s) => {
    const got = Buffer.from(s);
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}
```

Then, in the bin's **Webhooks** tab, add a **JSON** webhook to `https://your-site.example/api/hotcfg` for production, and set `HOTCFG_WEBHOOK_SECRET` to its `whsec_…` secret. Press **Send test**: your route answers `204`.

`{ expire: 0 }` makes the next request wait for the new config, which is what you want for a kill switch. For config where a few seconds of the old value don't matter, `revalidateTag("hotcfg", "max")` serves the old value once more while it fetches the new one.

## Notes

- **Next.js versions:** this uses `fetch`'s `next.tags` and the two-argument `revalidateTag`, as in current Next.js. With Cache Components, put the fetch in a `'use cache'` function and tag it with `cacheTag("hotcfg")` instead.
- **Private bins:** read from `https://private-api.hotcfg.run` and add `` headers: { Authorization: `Bearer ${process.env.HOTCFG_READ_KEY}` } `` with a publishable key limited to that bin. Keep the key in a server-side environment variable (no `NEXT_PUBLIC_` prefix). `cache: "force-cache"` caches it like any other fetch. See [Reading a bin](https://hotcfg.run/docs/reference/reading#private-bins).
- **Staging:** read `?env=staging` in preview deployments, for example by building the URL from `process.env.VERCEL_ENV`.
- **Gradual rollouts:** a server reads one version for everyone. To give a new version to some visitors first, pick a bucket per visitor (in a cookie) and add `?bucket=`; see [Progressive rollouts](https://hotcfg.run/docs/guides/rollouts).
- **Testing failures:** point `URL` at `?status=503` or `?delay=5000` to check that pages still render with the defaults. See [Testing slow and failing networks](https://hotcfg.run/docs/guides/testing-failures).

Last updated 17 November 2026
