From b221e2e4c0153bd4bbe070871f2267de9d46e0a5 Mon Sep 17 00:00:00 2001 From: batuhan Date: Wed, 28 Oct 2026 18:18:46 +0000 Subject: [PATCH 1/3] Document the supported Next.js versions --- content/(publish)/frameworks.mdx | 2 +- content/(publish)/recipes/next.mdx | 18 ++++++++++++++---- 2 files changed, 15 insertions(+), 5 deletions(-) diff --git a/content/(publish)/frameworks.mdx b/content/(publish)/frameworks.mdx index 1921a764..f21ecc37 100644 --- a/content/(publish)/frameworks.mdx +++ b/content/(publish)/frameworks.mdx @@ -230,4 +230,4 @@ Same routing conventions as the Astro integration, plus a check that the build i Wired for you. When `sf publish` runs `next build`, it points Next at the bundled adapter through `NEXT_ADAPTER_PATH`, so there is nothing to add to `next.config`. The adapter opts the build into immutable static assets and writes down what Next produced for the classifier to read. -Next 16.2 or newer is required for server-rendered builds, because that is the version where Next gained the `experimental.adapterPath` hook the adapter runs on. On an older Next, build with `output: "export"` and publish the export directory yourself. +The adapter runs on Next 16.2 and 16.3, the releases with the `experimental.adapterPath` hook it needs. Server-rendered builds also work on Next 15.5.24 and later 15.5 releases without the adapter. Other releases from 14.2 through 16.4 build only with `output: "export"`. See the [Next.js recipe](/recipes/next) for the full table. diff --git a/content/(publish)/recipes/next.mdx b/content/(publish)/recipes/next.mdx index 44beb0cf..03a66cf4 100644 --- a/content/(publish)/recipes/next.mdx +++ b/content/(publish)/recipes/next.mdx @@ -7,7 +7,17 @@ Next.js is detected by its `next` dependency. A project that also depends on `ne ## What to build -The default `next build`. Before it runs, the CLI points Next at the bundled `@spacefast/next-adapter` through the `NEXT_ADAPTER_PATH` environment variable, so there is nothing to add to `next.config`. The adapter opts the build into immutable static assets and writes down what Next produced for the classifier to read. +The default `next build`. On Next 16.2 and 16.3, the CLI first points Next at the bundled `@spacefast/next-adapter` through the `NEXT_ADAPTER_PATH` environment variable, so there is nothing to add to `next.config`. The adapter opts the build into immutable static assets and writes down what Next produced for the classifier to read. + +## Supported Next versions + +| Next.js | Server-rendered build | `output: "export"` | +| --- | --- | --- | +| 16.2.x, 16.3.x | Yes, through the bundled adapter | Yes | +| 15.5.24 and later 15.5 releases | Yes | Yes | +| 14.2, 15.0 to 15.5.23, 16.0, 16.1, 16.4 | No | Yes | + +Only stable releases count; canary and other prerelease versions are refused. ## The output directory @@ -32,15 +42,15 @@ Published: https://quiet-harbor.space.fast ## The gotcha -Automatic Next builds require **Next 16.2 or newer**. 16.2 is the version where Next gained the adapter hook the Spacefast adapter runs on, and the facts that adapter records are what turn the build into a serving plan. On anything older the CLI refuses before it builds: +A version outside the table, or a server-rendered build on a version that only supports exports, stops before it builds: ```text next_version_unsupported ``` -That is exit code 2. There is no fallback below the floor, because a publish classified from guessed facts is worse than a refused one. +That is exit code 2. There is no guessing fallback, because a publish classified from guessed facts is worse than a refused one. -On an older Next, do the export yourself and upload it: +On an export-only version, set `output: "export"` and let `sf publish` build it. On an unsupported version, do the export yourself and upload it: ```js next.config.js module.exports = { output: "export" }; From ce016e264157ef24508f37a9664f416270c1239a Mon Sep 17 00:00:00 2001 From: batuhan Date: Wed, 28 Oct 2026 18:22:14 +0000 Subject: [PATCH 2/3] Split the two Next.js version refusals --- content/(publish)/recipes/next.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/(publish)/recipes/next.mdx b/content/(publish)/recipes/next.mdx index 03a66cf4..f0c806e6 100644 --- a/content/(publish)/recipes/next.mdx +++ b/content/(publish)/recipes/next.mdx @@ -42,13 +42,13 @@ Published: https://quiet-harbor.space.fast ## The gotcha -A version outside the table, or a server-rendered build on a version that only supports exports, stops before it builds: +Both refusals fail with this code: ```text next_version_unsupported ``` -That is exit code 2. There is no guessing fallback, because a publish classified from guessed facts is worse than a refused one. +A version outside the table stops before anything builds. A server-rendered config on an export-only version runs `next build` first, then stops once the CLI sees the output is not an export. Both exit with code 2. There is no guessing fallback, because a publish classified from guessed facts is worse than a refused one. On an export-only version, set `output: "export"` and let `sf publish` build it. On an unsupported version, do the export yourself and upload it: @@ -61,4 +61,4 @@ npx next build sf publish ./out --prebuilt ``` -One related failure mode. If a custom build command runs `next build` in a way that loses the environment the CLI set, the adapter never runs. The publish then stops with `build_failed`, saying `.spacefast/next-build.json` was not written. Let the CLI invoke the build, or pass its environment through your wrapper. +One related failure mode on Next 16.2 and 16.3. If a custom build command runs `next build` in a way that loses the environment the CLI set, the adapter never runs. The publish then stops with `build_failed`, saying `.spacefast/next-build.json` was not written. Let the CLI invoke the build, or pass its environment through your wrapper. From 6922b97ced6cef78b9b67943bd74d6c9ef7aff0b Mon Sep 17 00:00:00 2001 From: batuhan Date: Wed, 28 Oct 2026 18:26:49 +0000 Subject: [PATCH 3/3] Scope the adapter wiring sentence to Next 16.2 and 16.3 --- content/(publish)/frameworks.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/(publish)/frameworks.mdx b/content/(publish)/frameworks.mdx index f21ecc37..d79d0200 100644 --- a/content/(publish)/frameworks.mdx +++ b/content/(publish)/frameworks.mdx @@ -228,6 +228,6 @@ Same routing conventions as the Astro integration, plus a check that the build i ### `@spacefast/next-adapter` -Wired for you. When `sf publish` runs `next build`, it points Next at the bundled adapter through `NEXT_ADAPTER_PATH`, so there is nothing to add to `next.config`. The adapter opts the build into immutable static assets and writes down what Next produced for the classifier to read. +Wired for you. When `sf publish` runs `next build` on Next 16.2 or 16.3, it points Next at the bundled adapter through `NEXT_ADAPTER_PATH`, so there is nothing to add to `next.config`. The adapter opts the build into immutable static assets and writes down what Next produced for the classifier to read. The adapter runs on Next 16.2 and 16.3, the releases with the `experimental.adapterPath` hook it needs. Server-rendered builds also work on Next 15.5.24 and later 15.5 releases without the adapter. Other releases from 14.2 through 16.4 build only with `output: "export"`. See the [Next.js recipe](/recipes/next) for the full table.