diff --git a/content/(publish)/frameworks.mdx b/content/(publish)/frameworks.mdx index 1921a764..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. -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..f0c806e6 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: +Both refusals fail with this code: ```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. +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 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" }; @@ -51,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.