Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions content/(publish)/frameworks.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
20 changes: 15 additions & 5 deletions content/(publish)/recipes/next.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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" };
Expand All @@ -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.
Loading