Verified compatibility

knext's goal is verified-adapter status: open source, validated against the official Next.js compatibility suite, honest about every exclusion. This page describes exactly what is verified, how, and what the claim does and does not cover.

What "the official suite" is

There is no @next/compat-suite npm package. The official compatibility harness is a mode of Next.js's own e2e suite: you check out vercel/next.js, build it, and run its deploy-eligible e2e tests with NEXT_TEST_MODE=deploy, pointing the harness at your adapter's lifecycle scripts. Each test then builds a real app through your adapter and runs its assertions over HTTP against the deployment your scripts produce — the same validation path the reference adapters use.

Runtime × builder cells

knext supports building and running a Next.js app in more than one shape. Each shape is its own compatibility cell, tracked with its own evidence:

• Standalone build, Node runtime. next build's own standalone output (server.js), booted under Node. Selectable — this is not a deprecated path.
• Standalone build, Bun runtime. Also selectable. The same standalone output, but compiled ahead of time into a single bytecode executable and run on Bun. This is what kn-next build produces when the standalone builder targets Bun.
• vinext build, Bun runtime. knext's own build pipeline, compiled into a bytecode single executable on Bun. This is the default build today.
• vinext build, Node runtime. The same vinext build, emitted for Node instead of compiled for Bun, and run with a V8 compile cache baked into the image. It builds and boots today; the suite has not been run against it yet.

How knext runs the suite

• Pinned upstream ref. The harness checks out vercel/next.js at a pinned release tag (currently v16.2.0) — never canary — so an upstream break is not mistaken for a knext regression.
• Real lifecycle scripts. The deploy tests run through knext's lifecycle scripts, which pack the @getknext/core adapter, set NEXT_ADAPTER_PATH, and boot each cell's own artifact — the standalone server.js under Node or Bun, or the compiled executable, depending on the cell under test.
• 16 shards, on a schedule. Each cell's suite run is sharded 16 ways (matching the reference adapter setup). Two kinds of scheduled run exist per cell — see Credentialing, below — plus manual dispatch.
• Red means red. A shard reporting any failed (or silently not-run) test fails the job, and a red scheduled run opens a tracking alarm. Any claim on this page is only as good as its most recently cited run, and the policy is to withdraw a claim the moment the run it rests on goes red.

Credentialing: what counts toward v1.0

A single green run — even a green nightly — is evidence, not a credential. knext's v1.0 bar asks for more:

• Every supported cell earns its own credential. There is no single "the suite is green" claim; each runtime × builder cell must independently bank 14 consecutive scheduled nights where every shard reports zero failed and zero not-run tests, and no new entry lands in the documented flaky-exceptions ledger for that cell.
• A credential night runs against a frozen release build of knext, not against the fast-moving main branch. This keeps a 14-night streak from being reset by unrelated day-to-day changes while it is banking.
• Nightly runs on the main branch are early warning only. They keep running, and a red one still raises an alarm, but they can never advance a cell toward its 14-night credential — only a scheduled run against a frozen release build counts.
• No cell is credentialed yet. A frozen release build for credentialing has not been cut, so no cell currently holds a 14-night streak. This page will be updated with per-cell credential status once a streak exists to report.

Results

The numbers below are what the most recent main-branch nightly (early warning, not a credential) has observed for each cell. Treat them as current evidence of where each cell stands today, not as a completed v1.0 credential.

What the claim covers — and what it doesn't

The tests run at the pinned ref are Next.js's own deploy-eligible e2e selection (including upstream's own per-case skips), minus two documented, auditable subtractions:

1 · Architectural exclusions (4 categories)

These are capabilities knext does not have, excluded openly rather than silently skipped:

2 · A per-case flaky-quarantine ledger

A small, evidence-guarded ledger quarantines individually-documented flaky tests. Every entry records the observed failure mechanism and its upstream provenance, and the ledger is guarded by a test so entries cannot be added without that evidence. It exists to keep the nightly signal clean — not to manufacture a green run.

The per-PR smoke gate

Independently of the official suite, a fast in-repo smoke gate runs on every change: it builds an example app through the adapter, boots it on a Node + Bun matrix, and hard-asserts real HTTP behavior (App Router HTML, RSC flight payloads, route handlers, dynamic/static routes, middleware header injection). The official suite is the correctness credential; the smoke gate is the minutes-fast regression tripwire in front of it.