@konduktor/build-info-next

Version/build metadata injection and /api/health endpoint for Next.js projects. Captures the BUILD_NUMBER env-var trick that makes Vercel deploys track a monotonic build number reliably.

Why this exists

Vercel's build environment has no git repository. git rev-list --count HEAD fails silently there, producing zero or stale build numbers. The only reliable source of a monotonic build number on Vercel is an env var (BUILD_NUMBER) set explicitly before each deploy.

This package captures the pattern so every Wombat project gets it for free.

Installation

pnpm add @konduktor/build-info-next

No peer dependencies — works with any Next.js 13+ project.

Usage

1. Wire into next.config.ts

// ✅ Recommended — main-entry import works in Next.js 13, 14, 15, and 16
import { withBuildInfo } from "@konduktor/build-info-next";

const nextConfig = withBuildInfo({
  reactStrictMode: true,
  // your other Next.js config
});

export default nextConfig;

Why the main entry and not @konduktor/build-info-next/config? Next.js 16's next.config.ts loader transpiles with a bundler that doesn't honor the ESM import condition alone on subpath exports, producing ERR_PACKAGE_PATH_NOT_EXPORTED. The main entry re-exports withBuildInfo so you get maximum compatibility. The /config subpath still works from plain Node and older Next.js versions if you prefer it. See docs/deploy-vercel.md Troubleshooting #1.

withBuildInfo() injects these env vars at build time:

• NEXT_PUBLIC_APP_VERSION — from package.json
• NEXT_PUBLIC_BUILD_NUMBER — from BUILD_NUMBER env var, or git rev-list --count HEAD fallback
• NEXT_PUBLIC_BUILD_ID — short git SHA
• NEXT_PUBLIC_BUILD_TIME — ISO timestamp of the build

2. Create the health endpoint

Create src/app/api/health/route.ts:

import { buildHealthResponse } from "@konduktor/build-info-next/health";

export async function GET() {
  return Response.json(buildHealthResponse());
}

Or with custom fields:

import { buildHealthResponse } from "@konduktor/build-info-next/health";
import { checkDatabase } from "@/lib/db";

export async function GET() {
  const dbOk = await checkDatabase();
  return Response.json(
    buildHealthResponse({
      database: dbOk ? "ok" : "down",
    }),
  );
}

Test it:

curl https://your-project.com/api/health
# { "status": "ok", "version": "0.23.1", "buildNumber": "743", "build": "bd26a26", "buildTime": "2026-04-11T13:45:00.000Z" }

3. Set BUILD_NUMBER in Vercel (critical)

For every deploy, set BUILD_NUMBER as a persistent env var on Vercel:

BUILD_NUM=$(git rev-list --count HEAD)

# Production:
npx vercel env rm BUILD_NUMBER production --yes 2>/dev/null
printf "%s" "$BUILD_NUM" | npx vercel env add BUILD_NUMBER production

# Preview (for staging):
# NOTE: --value and --yes flags do NOT work for Preview env.
# You must pipe the value and pass "" as the branch arg (= all preview branches).
npx vercel env rm BUILD_NUMBER preview --yes 2>/dev/null
printf "%s" "$BUILD_NUM" | npx vercel env add BUILD_NUMBER preview ""

Use printf, not echo. echo appends a trailing newline that Vercel stores literally, so /api/health returns "buildNumber": "44\n". See docs/deploy-vercel.md Troubleshooting #5.

Without this step, Vercel deploys will have wrong or stale build numbers.

Full deploy workflow: see ../../docs/deploy-vercel.md.

API reference

withBuildInfo(nextConfig, options?)

Next.js config wrapper. Injects build metadata as NEXT_PUBLIC_* env vars.

function withBuildInfo<T>(nextConfig?: T, options?: ResolveBuildInfoOptions): T;

Parameters:

• nextConfig — your existing Next.js config object (or empty)
• options — optional overrides for version/buildNumber/build/buildTime

Returns: extended Next.js config with env field populated.

buildHealthResponse(extra?)

Build a standard health response object.

function buildHealthResponse(extra?: Record<string, unknown>): HealthResponse;

Returns: object with status, version, buildNumber, build, buildTime, plus any extra fields merged.

getBuildInfo()

Read build info from NEXT_PUBLIC_* env vars. Use this in client components.

function getBuildInfo(): BuildInfo;

resolveBuildInfo(options?)

Resolve build info from env/git at build time (node-only, uses execSync). Use this inside next.config.ts or build scripts.

function resolveBuildInfo(options?: ResolveBuildInfoOptions): BuildInfo;

Self-hosted alternative

If you're not on Vercel, use @konduktor/build-info-docker (ships later) which uses a monotonic build-sequence.json artefact committed to the repo. Pattern from Grafto.

License

MIT © CryptoWombat