Production Guides & Recipes

Dual Route Pattern (Liveness & Readiness)

In Kubernetes and container platforms, configure two separate route handlers:

import { health } from "@/lib/health";
import { createNextHealthRoute } from "@nexload-sdk/healthcheck-next";

export const { GET } = createNextHealthRoute({
  health,
  scope: "liveness",
});

import { health } from "@/lib/health";
import { createNextHealthRoute } from "@nexload-sdk/healthcheck-next";

export const { GET } = createNextHealthRoute({
  health,
  scope: "readiness",
});

Protecting Diagnostics Endpoints

Detailed diagnostic reports should not be public. Protect them with secret tokens:

import { health } from "@/lib/health";
import { createNextHealthRoute } from "@nexload-sdk/healthcheck-next";

export const { GET } = createNextHealthRoute({
  health,
  scope: "diagnostics",
  security: {
    token: process.env.DIAGNOSTICS_SECRET_TOKEN,
  },
});

Requests must include either:

Authorization: Bearer <token>
Header X-Health-Token: <token>
Query parameter ?token=<token>

Troubleshooting & Common Pitfalls

1. Next.js Static Compilation Stale Responses

If Next.js attempts to statically pre-render the route at build time, ensure you export dynamic = 'force-dynamic' or let createNextHealthRoute set dynamic runtime headers automatically:

export const dynamic = "force-dynamic";

2. Edge Runtime Incompatibility with Node Checks

If your Next.js route uses export const runtime = 'edge', do not include Node-specific checks (like containerResourceCheck or dnsCheck) in your health manager. Use edge-safe core checks or run the health route on the standard Node runtime.