knext v1.3.0

knext v1.3.0

This is the stable release of the 1.3 line, published to the npm dist-tag latest. It is
1.3.0-rc.10 promoted to GA: the published files are identical to 1.3.0-rc.10 except for the
version string. Nothing was added, removed or fixed between the two.

If you are already on 1.3.0-rc.10, there is nothing to change in your app except the version
number. The v1.0 line stays installable under the latest-1.0 dist-tag.

What's in 1.3.0

The 1.3 line is built from the following release candidates, each documented in its own notes under
docs/release/. The change in the last one is:

Fixed: vinext lists Pages Router routes in _buildManifest.js

This is a vinext patch bundled with knext until a vinext release includes it. The upstream pull
request is linked.

• sortedPages in _buildManifest.js. On the vinext target, an app with a Pages Router has
  its routes (API routes, /_app and /_error included) listed in sortedPages of
  /_next/static/<buildId>/_buildManifest.js, in Next.js order. Before, the list was empty
  (cloudflare/vinext#3774).

What this release does not claim

• No performance or compatibility claim. No measurement is made or implied for this release.
• No compatibility credential. knext's compatibility credential (14 consecutive green runs of
  the official Next.js compatibility suite) covers four combinations: Node and Bun, each with
  Turbopack and webpack. That credential is still in progress and is not earned by this
  release. Shipping 1.3.0 is a version decision, not a statement that the credential has been met.
• vinext is Beta. The vinext target is not credentialed, and this release does not change that.

Install

npm i @getknext/core

@getknext/lib and @getknext/db are installed at the same version through @getknext/core's
dependencies. To run the CLI without installing:

npx -p @getknext/core knext --help

To stay on the v1.0 line instead, install @getknext/core@latest-1.0.

Upgrade notes

• Upgrade the operator (and its CRD) first, then the CLI, once an operator release from this line
  exists (see Known issues). This release adds no new NextApp field.
• The PrivateExposure warning (added in 1.3.0-rc.5) needs an operator built from the 1.3
  line. The published operator images do not include it; upgrade the operator before relying on
  the warning.
• latest moves to this line. @getknext/core@latest now resolves to 1.3.0. Pin an exact
  version (@getknext/core@1.3.0) if you need the install to stay fixed, or use latest-1.0 to
  stay on the v1.0 line.

Package delta against 1.3.0-rc.10

Checked by packing the tarballs and comparing them file by file with the published
1.3.0-rc.10 tarballs. The only difference is the version string. Operator (not an npm package):
no change, and no new NextApp field.

Known issues

• No published operator release supports this line's two new NextApp fields yet. The
  operator releases (operator-latest, and the rolling operator-edge) are built from the v1.0
  line, whose CRD has neither spec.networking.visibility (1.3.0-rc.4) nor
  spec.security.writeFree (1.3.0-rc.2). A deploy that sets either field fails the deploy
  preflight with an unknown field error, before anything reaches the cluster. Against those
  operators:

  • private apps cannot be deployed (networking.visibility: "cluster-local" or --private);
  • a vinext app in its default (not self-contained) mode fails knext deploy when the CLI
    builds the image in the same run, which is the normal case, on either runtime, because the
    CLI then sets spec.security.writeFree;
  • a standalone app with storage configured fails knext deploy when the CLI builds the
    image in the same run. The preflight runs before the build and assumes the field, so building
    with KNEXT_IMAGE_CACHE_HANDLER=0 does not avoid it. Standalone self-contained executables
    fail the same way.

  Other standalone apps deploy as before. What to do until an operator release from
  this line is published:

  • standalone apps with storage or a self-contained executable: stay on the v1.0 line
    (@getknext/core@latest-1.0);
  • vinext on Bun: use 1.3.0-rc.1, which sets neither field. 1.0.0 does not work for
    a vinext app created on this line, because its scaffold runs knext vinext-patches on install
    and that command does not exist before 1.3.0-rc.1;
  • vinext on Node, and standalone apps with storage that need this line: there is no tested
    workaround yet.

• A custom domain makes a private app public. Private apps only mark the app's Knative
  Service as cluster-local. A Knative DomainMapping that points at that service is still routed
  through the public load balancer, even if the DomainMapping itself is labelled cluster-local.
  So adding a custom domain to a private app silently publishes it. Do not add a DomainMapping
  to a private app (an operator from this line warns about it; the published operator images do
  not yet). To reach one from outside the cluster, run a tunnel to the cluster's internal
  gateway that rewrites the Host header, behind an identity-aware proxy.

• The "Edge Runtime is deprecated" warning does not yet match Next.js on the vinext target.
  Next.js's own test for that warning still fails, so treat it as not yet fixed.

• The vinext shebang fix from 1.3.0-rc.2 has two known limits:

  • A byte-order mark (BOM) before the shebang line is not detected, so such a file still fails to
    build.
  • Source maps for a file whose shebang was stripped and reattached are one line off, which can
    point a debugger or stack trace at the wrong line for that file.

• Patched Bun toolchain (experimental, opt-in compile.bun: 'knext-patched'): unchanged from
  1.3.0-rc.1. There is no cluster-deploy proof yet, each binary's SBOM records only the file and
  its digest, the binaries are compiled on a shared build service account, and the compile step is
  about 4–5% slower than stock Bun.

---

Packages

Package	npm	Changelog
@getknext/core	1.3.0	CHANGELOG
@getknext/lib	1.3.0	CHANGELOG
@getknext/db	1.3.0	CHANGELOG

These notes are also in the repository at docs/release/v1.3.0.md.