Compatibility & the official suite
The two layers of compatibility testing, and what knext does and does not yet claim.
knext's goal is verified-adapter status: open source, passing the official Next.js compatibility suite, and listed in the Next.js docs. This page explains the two testing layers behind that goal and is honest about where each stands.
Verified-adapter status is the goal, not a current claim. knext does not currently pass the
official vercel/next.js compatibility suite, and no knext doc may say it does until the official
harness is green nightly. The per-PR smoke gate below is knext's own suite — useful, but explicitly
not the official one.
Two layers
| Layer | Job | Trigger | What it proves |
|---|---|---|---|
| Smoke | compat-smoke | Every PR | knext's own HTTP assertions pass on Node + Bun. |
| Official | compat-suite | Nightly + manual dispatch | A real partial subset of the official vercel/next.js deploy-test harness. Not yet green. |
The per-PR compat-smoke gate
compat-smoke is a small, in-repo sanity suite that runs on every PR. It builds an example app
through the knext adapter (output: 'standalone'), boots the standalone server.js, and runs
real HTTP assertions against it. The CI job runs it on a Node + Bun matrix and is red on
failure.
The checks it asserts against the running server:
| Check | Asserts |
|---|---|
App Router page (GET /) | 200, text/html, non-trivial body |
RSC flight (GET / with RSC: 1) | 200, content-type: text/x-component |
Route handler (GET /api/health) | 200, valid JSON |
Dynamic route (force-dynamic) | 200 |
Static route (force-static) | 200 |
| Middleware (Node runtime) | injected x-knext-smoke: 1 header is present |
next/image optimization | 200 with content-type: image/* (skip-on-fail, not a hard gate) |
compat-smoke is NOT the official suite. The script and its CI job label themselves that way.
These are knext's own assertions on the routes it claims to support — a fast (~minutes) correctness
gate, not Next.js's validation. The next/image check is skip-on-fail, so a green run does not
prove image optimization. See the compatibility matrix for the evidence-gated,
per-feature status.
The official vercel/next.js deploy-test harness
There is no @next/compat-suite npm package. The official "compatibility test harness" is a mode
of Next.js's own e2e suite: you check out vercel/next.js, build it, and run its tests with
NEXT_TEST_MODE=deploy, pointing the harness at your adapter's lifecycle scripts.
knext wires this up as an MVP:
- Checks out
vercel/next.jsat a pinned ref (defaultv16.0.3, matching the in-reponext) — nevercanary, so an upstream break is not mistaken for a knext regression. - Runs the deploy tests via knext's lifecycle scripts, which pack the adapter, set
NEXT_ADAPTER_PATH, build, and boot the standaloneserver.js. - Triggers on a nightly schedule and manual dispatch. As an MVP it runs a modest 4-way shard (the reference uses 16) and Node runtime only to start.
This harness is NOT yet green. It runs a real partial subset of the official deploy tests, but knext does not currently pass the full suite and makes no "verified-adapter" claim. The official-suite row in the compatibility matrix stays ❌ until a green nightly.
The exclude-list as an honest ledger
The harness layers a knext manifest on top of Next's own test-selection manifest. Its exclude list
is an honest ledger, not a way to manufacture a green run. The principle: no silent skips —
every exclusion names a category knext does not support and why, and the list must grow from
observed failures and shrink toward zero as the verified-adapter scoreboard.
Today it excludes the upstream-gated, architecturally-out-of-scope categories:
| Excluded category | Why |
|---|---|
| Edge Runtime | knext targets the Node/Bun standalone server; it has no edge (V8-isolate) runtime. |
| Edge Middleware | Edge Middleware needs the Edge Runtime; knext supports the Node middleware convention only. |
| PPR | Partial Prerendering is not adapter-standardizable yet (upstream-gated). |
| Cache Components | 'use cache' / cacheLife is an evolving upstream API not yet stabilized for adapters. |
A row graduates to ✅ only from a real green run — never pre-emptively. Only after the full harness is green nightly may any knext doc use the words "passes the official Next.js adapter compatibility suite."
For the per-feature status of what knext supports today — each row backed by on-disk evidence and a CI guard test — see the compatibility matrix.