Turbopack: Add --experimental-server-fast-refresh CLI flag

[wbinnssmith]

This adds --experimental-server-fast-refresh CLI flag to enable experimental server-side Fast Refresh (HMR) during development. It's disabled by default.

We call HMR "fast refresh" in public docs so let's keep the flag consistent with that. We use the HMR naming past this outer layer in the codebase.

Test Plan:

next dev --experimental-server-fast-refresh

[wbinnssmith]

• Turbopack: make JavaScript runtimes moduleCache a Map #89515
• Turbopack: Implement server hmr in nodejs dev runtime #89130
• Turbopack: extract core hmr client logic into shared runtime #88912
• Turbopack: Reorganize runtime files into shared/runtime directory #89461
• Turbopack: Server HMR infrastructure #88870
• Turbopack: Add --experimental-server-fast-refresh CLI flag #89274 👈 (View in Graphite)
• canary

This stack of pull requests is managed by Graphite. Learn more about stacking.

[nextjs-bot]

Tests Passed

[nextjs-bot]

Stats from current PR

✅ No significant changes detected

📊 All Metrics

📖 Metrics Glossary

Dev Server Metrics:

• Listen = TCP port starts accepting connections
• First Request = HTTP server returns successful response
• Cold = Fresh build (no cache)
• Warm = With cached build artifacts

Build Metrics:

• Fresh = Clean build (no .next directory)
• Cached = With existing .next directory

Change Thresholds:

• Time: Changes < 50ms AND < 10%, OR < 2% are insignificant
• Size: Changes < 1KB AND < 1% are insignificant
• All other changes are flagged to catch regressions

⚡ Dev Server

Metric	Canary	PR	Change	Trend
Cold (Listen)	455ms	455ms	✓	▁▄█▁▁
Cold (Ready in log)	438ms	439ms	✓	▅▄█▄▅
Cold (First Request)	1.185s	1.169s	✓	█▃▆▇▆
Warm (Listen)	456ms	457ms	✓	▁▅█▁▁
Warm (Ready in log)	443ms	444ms	✓	▁▄█▁▁
Warm (First Request)	339ms	342ms	✓	▃▃█▄▄

📦 Dev Server (Webpack) (Legacy)

📦 Dev Server (Webpack)

Metric	Canary	PR	Change	Trend
Cold (Listen)	505ms	505ms	✓	█▁▁▁▁
Cold (Ready in log)	459ms	460ms	✓	▆▄▅▅▅
Cold (First Request)	1.942s	1.960s	✓	▅▂▄▃▃
Warm (Listen)	506ms	505ms	✓	█▁▁▁▁
Warm (Ready in log)	464ms	461ms	✓	▆▄▄▅▅
Warm (First Request)	1.946s	1.982s	✓	▆▂▄▃▃

⚡ Production Builds

Metric	Canary	PR	Change	Trend
Fresh Build	3.912s	3.949s	✓	▁▅█▁▁
Cached Build	3.975s	3.952s	✓	▁▅█▁▁

📦 Production Builds (Webpack) (Legacy)

📦 Production Builds (Webpack)

Metric	Canary	PR	Change	Trend
Fresh Build	14.518s	14.510s	✓	▆▁▅▁▁
Cached Build	14.542s	14.604s	✓	▆▁▆▂▁
node_modules Size	467 MB	467 MB	✓	▁▁███

📦 Bundle Sizes

Bundle Sizes

⚡ Turbopack

Client

Main Bundles: **437 kB** → **437 kB** ⚠️ +2 B

81 files with content-based hashes (individual files not comparable between builds)

Server

Middleware

	Canary	PR	Change
middleware-b..fest.js gzip	764 B	764 B	✓
Total	764 B	764 B	✓

Build Details

Build Manifests

	Canary	PR	Change
_buildManifest.js gzip	452 B	451 B	✓
Total	452 B	451 B	✅ -1 B

📦 Webpack

Client

Main Bundles

	Canary	PR	Change
5528-HASH.js gzip	5.47 kB	N/A	-
6280-HASH.js gzip	56.9 kB	N/A	-
6335.HASH.js gzip	169 B	N/A	-
912-HASH.js gzip	4.53 kB	N/A	-
e8aec2e4-HASH.js gzip	62.5 kB	N/A	-
framework-HASH.js gzip	59.7 kB	59.7 kB	✓
main-app-HASH.js gzip	256 B	254 B	✓
main-HASH.js gzip	39.1 kB	39.1 kB	✓
webpack-HASH.js gzip	1.68 kB	1.68 kB	✓
262-HASH.js gzip	N/A	4.52 kB	-
2889.HASH.js gzip	N/A	169 B	-
5602-HASH.js gzip	N/A	5.48 kB	-
6948ada0-HASH.js gzip	N/A	62.5 kB	-
9544-HASH.js gzip	N/A	57.5 kB	-
Total	230 kB	231 kB	⚠️ +606 B

Polyfills

	Canary	PR	Change
polyfills-HASH.js gzip	39.4 kB	39.4 kB	✓
Total	39.4 kB	39.4 kB	✓

Pages

	Canary	PR	Change
_app-HASH.js gzip	194 B	194 B	✓
_error-HASH.js gzip	183 B	180 B	🟢 3 B (-2%)
css-HASH.js gzip	331 B	330 B	✓
dynamic-HASH.js gzip	1.81 kB	1.81 kB	✓
edge-ssr-HASH.js gzip	256 B	256 B	✓
head-HASH.js gzip	351 B	352 B	✓
hooks-HASH.js gzip	384 B	383 B	✓
image-HASH.js gzip	580 B	581 B	✓
index-HASH.js gzip	260 B	260 B	✓
link-HASH.js gzip	2.49 kB	2.49 kB	✓
routerDirect..HASH.js gzip	320 B	319 B	✓
script-HASH.js gzip	386 B	386 B	✓
withRouter-HASH.js gzip	315 B	315 B	✓
1afbb74e6ecf..834.css gzip	106 B	106 B	✓
Total	7.97 kB	7.97 kB	✅ -1 B

Server

Edge SSR

	Canary	PR	Change
edge-ssr.js gzip	126 kB	126 kB	✓
page.js gzip	249 kB	249 kB	✓
Total	375 kB	375 kB	⚠️ +471 B

Middleware

	Canary	PR	Change
middleware-b..fest.js gzip	616 B	616 B	✓
middleware-r..fest.js gzip	156 B	155 B	✓
middleware.js gzip	33.1 kB	33.2 kB	✓
edge-runtime..pack.js gzip	842 B	842 B	✓
Total	34.7 kB	34.8 kB	⚠️ +80 B

Build Details

Build Manifests

	Canary	PR	Change
_buildManifest.js gzip	732 B	736 B	✓
Total	732 B	736 B	⚠️ +4 B

Build Cache

	Canary	PR	Change
0.pack gzip	3.84 MB	3.85 MB	🔴 +9.59 kB (+0%)
index.pack gzip	103 kB	103 kB	✓
index.pack.old gzip	103 kB	104 kB	✓
Total	4.05 MB	4.06 MB	⚠️ +11.2 kB

🔄 Shared (bundler-independent)

Runtimes

	Canary	PR	Change
app-page-exp...dev.js gzip	315 kB	315 kB	✓
app-page-exp..prod.js gzip	167 kB	167 kB	✓
app-page-tur...dev.js gzip	315 kB	315 kB	✓
app-page-tur..prod.js gzip	167 kB	167 kB	✓
app-page-tur...dev.js gzip	311 kB	311 kB	✓
app-page-tur..prod.js gzip	165 kB	165 kB	✓
app-page.run...dev.js gzip	312 kB	312 kB	✓
app-page.run..prod.js gzip	165 kB	165 kB	✓
app-route-ex...dev.js gzip	70.5 kB	70.5 kB	✓
app-route-ex..prod.js gzip	49 kB	49 kB	✓
app-route-tu...dev.js gzip	70.5 kB	70.5 kB	✓
app-route-tu..prod.js gzip	49 kB	49 kB	✓
app-route-tu...dev.js gzip	70.1 kB	70.1 kB	✓
app-route-tu..prod.js gzip	48.8 kB	48.8 kB	✓
app-route.ru...dev.js gzip	70.1 kB	70.1 kB	✓
app-route.ru..prod.js gzip	48.7 kB	48.7 kB	✓
dist_client_...dev.js gzip	324 B	324 B	✓
dist_client_...dev.js gzip	326 B	326 B	✓
dist_client_...dev.js gzip	318 B	318 B	✓
dist_client_...dev.js gzip	317 B	317 B	✓
pages-api-tu...dev.js gzip	43.2 kB	43.2 kB	✓
pages-api-tu..prod.js gzip	32.9 kB	32.9 kB	✓
pages-api.ru...dev.js gzip	43.1 kB	43.1 kB	✓
pages-api.ru..prod.js gzip	32.8 kB	32.8 kB	✓
pages-turbo....dev.js gzip	52.5 kB	52.5 kB	✓
pages-turbo...prod.js gzip	39.4 kB	39.4 kB	✓
pages.runtim...dev.js gzip	52.4 kB	52.4 kB	✓
pages.runtim..prod.js gzip	39.3 kB	39.3 kB	✓
server.runti..prod.js gzip	62.7 kB	62.7 kB	✓
Total	2.79 MB	2.79 MB	⚠️ +1 B

[bgw]