Repository navigation
Document the Next.js versions Spacefast builds #137
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,23 +1,22 @@ | ||
| --- | ||
| title: Next.js | ||
| description: Build a Next.js app with the bundled Spacefast adapter, or publish a static export from an older Next | ||
| description: Build a Next.js app with the bundled Spacefast adapter on a supported, patched Next release | ||
| --- | ||
|
|
||
| Next.js is detected by its `next` dependency. A project that also depends on `nextra` matches the Nextra row instead, which builds and outputs the same way. | ||
|
|
||
| ## What to build | ||
|
|
||
| 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. | ||
| The default `next build`. On Next 16.4.5 and later 16.4 releases, 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 | | ||
| | 16.4.5 and later 16.4 releases | Yes, through the bundled adapter | Yes | | ||
| | 15.5.29 and later 15.5 releases | Yes | Yes | | ||
|
|
||
| Only stable releases count; canary and other prerelease versions are refused. | ||
| Spacefast builds the same releases its server bundler, OpenNext, supports. Its minimum versions follow Next.js security releases, so every older release has published [security advisories](https://github.com/vercel/next.js/security/advisories), and Spacefast refuses to build it. Only stable releases count; canary and other prerelease versions are refused. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ⚪️ Nit · "Same releases OpenNext supports" doesn't describe the 15.5 row In #5738 only the 16.4 profile uses OpenNext 1.20.17. The 15.5 legacy-server path still pins Found by Indent Review Agent |
||
|
|
||
| ## The output directory | ||
|
|
||
|
|
@@ -42,15 +41,15 @@ Published: https://quiet-harbor.space.fast | |
|
|
||
| ## The gotcha | ||
|
|
||
| Both refusals fail with this code: | ||
| A version outside the table fails with this code, before anything builds, and exits with code 2: | ||
|
|
||
| ```text | ||
| next_version_unsupported | ||
| ``` | ||
|
|
||
| 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. | ||
| For an older release, the error says it has known security vulnerabilities and names the version to upgrade to. Upgrade, then publish again. 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: | ||
| If you can't upgrade yet, build a static export yourself and upload it: | ||
|
|
||
| ```js next.config.js | ||
| module.exports = { output: "export" }; | ||
|
|
@@ -61,4 +60,4 @@ npx next build | |
| sf publish ./out --prebuilt | ||
| ``` | ||
|
|
||
| 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. | ||
| One related failure mode on Next 16.4. 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. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🟡 Bug · Documented version policy doesn't match the CLI in monorepo#5738
This table drops 16.2.x, 16.3.x and raises the 15.5 floor to 29, but spacefast/monorepo#5738 (open, head a9ff9279) still has the 16.2/16.3 adapter profiles in
packages/cli/src/next-build-compatibility.ts,LEGACY_SERVER_RANGE = ">=15.5.24 <16.0.0", and accepts 14.2, 15.0 to 15.5.x and 16.0 to 16.4.4 as automatic static exports. Its refusal message says nothing about security advisories or an upgrade version. The same claims are in frameworks.mdx and migrate-from/vercel.mdx. Align the CLI or the docs before merging.Found by Indent Review Agent