next.config.js: Accept an option for serverFastRefresh#91968
Merged
wbinnssmith merged 9 commits intocanaryfrom Mar 31, 2026
Merged
next.config.js: Accept an option for serverFastRefresh#91968wbinnssmith merged 9 commits intocanaryfrom
wbinnssmith merged 9 commits intocanaryfrom
Conversation
Currently we support opting out of server fast refresh via the cli. Certain Next.js plugins have encountered issues with it (which we're addressing separately) and may want to opt the user out for the time being. This implements that. Test Plan: - [ ] Added e2e development test
Collaborator
Tests Passed |
…sing test fixtures - Fix Commander's --no-server-fast-refresh option to correctly produce `undefined` (not `true`) when no flag is passed, by adding a hidden positive `--server-fast-refresh` option with `default(undefined)` - Add `?? true` default in router-server.ts so server HMR is enabled when neither CLI nor config specifies a value - Remove non-existent tsconfig.json FileRef from test suites (tsconfig is auto-generated by the test harness; test/.gitignore ignores it) Co-Authored-By: Claude <[email protected]>
Collaborator
Stats from current PR✅ No significant changes detected📊 All Metrics📖 Metrics GlossaryDev Server Metrics:
Build Metrics:
Change Thresholds:
⚡ Dev Server
📦 Dev Server (Webpack) (Legacy)📦 Dev Server (Webpack)
⚡ Production Builds
📦 Production Builds (Webpack) (Legacy)📦 Production Builds (Webpack)
📦 Bundle SizesBundle Sizes⚡ TurbopackClient Main Bundles
Server Middleware
Build DetailsBuild Manifests
📦 WebpackClient Main Bundles
Polyfills
Pages
Server Edge SSR
Middleware
Build DetailsBuild Manifests
Build Cache
🔄 Shared (bundler-independent)Runtimes
📎 Tarball URL |
Co-Authored-By: Claude <[email protected]>
Co-Authored-By: Claude <[email protected]>
…ntal) Co-Authored-By: Claude <[email protected]>
lukesandberg
approved these changes
Mar 27, 2026
sokra
reviewed
Mar 27, 2026
Addresses reviewer feedback: since this feature is Turbopack-specific, it belongs under experimental with the turbopack* naming convention. Co-Authored-By: Claude <[email protected]>
wbinnssmith
added a commit
that referenced
this pull request
Mar 31, 2026
### What? Adds `experimental.serverFastRefresh` to `next.config.js` so users (and Next.js plugins) can opt out of server-side Fast Refresh without needing to pass a CLI flag. Also adds a `--server-fast-refresh` positive CLI flag (hidden) alongside the existing `--no-server-fast-refresh`, and emits a warning when the CLI flag and config value conflict. This is a necessary implementation detail for `commander` to detect when no option is provided. ### Why? Certain Next.js plugins have encountered issues with server Fast Refresh and need a way to disable it programmatically via config rather than requiring users to modify their start scripts. The CLI-only opt-out (`--no-server-fast-refresh`) was insufficient for this use case. ### How? - **`config-shared.ts` / `config-schema.ts`**: Added `experimental.serverFastRefresh?: boolean` to the `ExperimentalConfig` type and Zod schema. - **`router-server.ts`**: Resolves the effective `serverFastRefresh` value at startup by combining the CLI flag (`opts.serverFastRefresh`) and `nextConfig.experimental.serverFastRefresh`, with CLI taking precedence. Emits a `Log.warn` when both are set to conflicting values. Defaults to `true` when neither is specified. - **`bin/next.ts`**: Fixed the Commander option definition for `--no-server-fast-refresh`. Commander's `--no-X` pattern implicitly creates a positive `--server-fast-refresh` option defaulting to `true`, which meant `opts.serverFastRefresh` was never `undefined` and the config value could never take effect. Fixed by explicitly registering a hidden `--server-fast-refresh` option with `.default(undefined)`. - **Tests**: Added two new test suites in `test/development/app-dir/server-hmr/server-hmr.test.ts`: - `server-hmr config opt-out` — verifies that setting `experimental.serverFastRefresh: false` in config causes unmodified dependencies to be re-evaluated (i.e., server HMR is disabled). - `server-hmr CLI/config conflict warning` — verifies that passing `--no-server-fast-refresh` when config has `serverFastRefresh: true` logs the conflict warning. ### Test Plan - [x] Added e2e development tests (`test/development/app-dir/server-hmr/server-hmr.test.ts`) — all 8 tests pass --------- Co-authored-by: Will Binns-Smith <[email protected]> Co-authored-by: Claude <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Adds
experimental.serverFastRefreshtonext.config.jsso users (and Next.js plugins) can opt out of server-side Fast Refresh without needing to pass a CLI flag.Also adds a
--server-fast-refreshpositive CLI flag (hidden) alongside the existing--no-server-fast-refresh, and emits a warning when the CLI flag and config value conflict. This is a necessary implementation detail forcommanderto detect when no option is provided.Why?
Certain Next.js plugins have encountered issues with server Fast Refresh and need a way to disable it programmatically via config rather than requiring users to modify their start scripts. The CLI-only opt-out (
--no-server-fast-refresh) was insufficient for this use case.How?
config-shared.ts/config-schema.ts: Addedexperimental.serverFastRefresh?: booleanto theExperimentalConfigtype and Zod schema.router-server.ts: Resolves the effectiveserverFastRefreshvalue at startup by combining the CLI flag (opts.serverFastRefresh) andnextConfig.experimental.turbopackServerFastRefresh, with CLI taking precedence. Emits aLog.warnwhen both are set to conflicting values. Defaults totruewhen neither is specified.bin/next.ts: Fixed the Commander option definition for--no-server-fast-refresh. Commander's--no-Xpattern implicitly creates a positive--server-fast-refreshoption defaulting totrue, which meantopts.serverFastRefreshwas neverundefinedand the config value could never take effect. Fixed by explicitly registering a hidden--server-fast-refreshoption with.default(undefined).test/development/app-dir/server-hmr/server-hmr.test.ts:server-hmr config opt-out— verifies that settingexperimental.serverFastRefresh: falsein config causes unmodified dependencies to be re-evaluated (i.e., server HMR is disabled).server-hmr CLI/config conflict warning— verifies that passing--no-server-fast-refreshwhen config hasserverFastRefresh: truelogs the conflict warning.Test Plan
test/development/app-dir/server-hmr/server-hmr.test.ts) — all 8 tests pass