Skip to content

Reload affected WebSocket routes in development - #97031

Draft
DavidIlie wants to merge 5 commits into
codex/websocket-route-generationsfrom
codex/websocket-route-handlers-hmr
Draft

Reload affected WebSocket routes in development#97031
DavidIlie wants to merge 5 commits into
codex/websocket-route-generationsfrom
codex/websocket-route-handlers-hmr

Conversation

@DavidIlie

@DavidIlie DavidIlie commented Aug 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What?

Reload only the WebSocket Route Handlers affected by a development server update, and document the completed experimental feature.

Why?

Closing every persistent connection on each development update makes WebSocket applications difficult to work on. Once lifecycle and route-generation ownership exist, Next.js can invalidate only the routes whose server code changed while leaving unrelated connections alive.

How?

  • Close affected connections with 1012 when their route or one of its dependencies changes.
  • Support Turbopack and Webpack, shared dependencies, deletion and restoration, route-group moves, and Node-to-Edge transitions.
  • Avoid route-graph traversal when no WebSocket route is active.
  • Keep the compatible route-HMR cases running under Cache Components, skipping only the unsupported Node-to-Edge runtime transition.
  • Add the complete NextResponse.upgrade() guide, API reference, deployment behavior, reconnection guidance, and process-local policy boundaries.
  • Document the single-owner dispatcher contract for custom servers hosting multiple Next.js apps or WebSocket protocols.

This is stacked on #97030 and completes the seven-PR experimental WebSocket Route Handler stack.

Verification

  • pnpm test-dev-turbo test/development/app-dir/server-hmr/server-hmr.test.ts -t "WebSocket route HMR"
  • The same focused suite with Cache Components enabled
  • Corresponding webpack WebSocket HMR coverage
  • pnpm test-dev-turbo test/e2e/app-dir/websocket-route-handlers/websocket-route-handlers.test.ts
  • pnpm build-all
  • pnpm types-and-precompiled
  • Documentation formatting and link validation

@github-actions

github-actions Bot commented Aug 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Tests Passed

Commit: c768b81

@github-actions

github-actions Bot commented Aug 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Stats from current PR

🔴 1 regression

Metric Canary PR Change Trend
node_modules Size 553 MB 556 MB 🔴 +3.07 MB (+1%) █████
📊 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) 813ms 813ms ✓ █████
Cold (Ready in log) 801ms 814ms ✓ ▅▃▄█▆
Cold (First Request) 1.368s 1.363s ✓ ▄▂▂█▇
Warm (Listen) 814ms 816ms ✓ ▅▄▄▅▅
Warm (Ready in log) 807ms 819ms ✓ ▃▂▃▆▄
Warm (First Request) 1.346s 1.340s ✓ ▂▁▂▇▅
📦 Dev Server (Webpack) (Legacy)

📦 Dev Server (Webpack)

Metric Canary PR Change Trend
Cold (Listen) 813ms 814ms ✓ █████
Cold (Ready in log) 819ms 817ms ✓ ▇▃█▅▆
Cold (First Request) 3.546s 3.539s ✓ █▄█▇▇
Warm (Listen) 863ms 813ms ✓ █▅██▅
Warm (Ready in log) 825ms 816ms ✓ ▇▃█▇▇
Warm (First Request) 3.615s 3.549s ✓ █▃▆▆▄

⚡ Production Builds

Metric Canary PR Change Trend
Fresh Build 6.332s 6.251s ✓ ▃▁▃█▆
Cached Build 3.044s 3.094s ✓ ▄▁▂█▇
📦 Production Builds (Webpack) (Legacy)

📦 Production Builds (Webpack)

Metric Canary PR Change Trend
Fresh Build 25.730s 26.023s ✓ ▇▂█▅▇
Cached Build 26.086s 26.283s ✓ █▁█▆▇
node_modules Size 553 MB 556 MB 🔴 +3.07 MB (+1%) █████
📦 Bundle Sizes

Bundle Sizes

⚡ Turbopack

Client

Main Bundles
Canary PR Change
050icza-xjz0i.js gzip 5.73 kB N/A -
075w8k05wqbxg.js gzip 152 B N/A -
07jdby0ue616s.js gzip 450 B N/A -
0bjdc8muo74n5.js gzip 8.71 kB N/A -
0cz1d0mv5g_q7.js gzip 39.4 kB 39.4 kB ✓
0fz75kvm47217.js gzip 157 B N/A -
0rci1f3or1a19.js gzip 13.3 kB N/A -
0v2vdqju5d3us.js gzip 65.6 kB N/A -
0wymx6umcmr-e.js gzip 156 B N/A -
1_2x714--ii1i.js gzip 8.76 kB N/A -
1-3y752pkth5-.js gzip 10 kB N/A -
194z3nzvcclm4.js gzip 158 B N/A -
1b2kxnxiyh5td.js gzip 156 B N/A -
1elt1qium-r2m.css gzip 115 B 115 B ✓
1hy0e5cihni_x.js gzip 7.54 kB N/A -
1k6dd7su4cfei.js gzip 3.57 kB N/A -
1n_j1oyi21iiv.js gzip 71.5 kB N/A -
1p_-361sg-xor.js gzip 156 B N/A -
1p-3_vnu3i9w8.js gzip 156 B N/A -
1tf1phijqlx9j.js gzip 220 B 220 B ✓
1uzabyd1120a1.js gzip 8.71 kB N/A -
2-ufv8lc-g7gg.js gzip 10.6 kB N/A -
21kmjy_10x14f.js gzip 8.81 kB N/A -
28dhc6t85q1_p.js gzip 8.78 kB N/A -
2d-9gbr1pinw0.js gzip 156 B N/A -
2f-ilvczue-tp.js gzip 9.46 kB N/A -
2f1u17u5c8iny.js gzip 8.79 kB N/A -
2ikltg_8iegxw.js gzip 10.3 kB N/A -
2iupp4nrd6c1_.js gzip 156 B N/A -
2roru2mb_p8yo.js gzip 168 B N/A -
2vxi673cz1-t4.js gzip 8.79 kB N/A -
3_5ebngsihghe.js gzip 159 B N/A -
38-q43pzktqhs.js gzip 1.46 kB N/A -
3e42tdpo_93le.js gzip 161 B N/A -
3mrwxzed0ylgv.js gzip 13.1 kB N/A -
3nbojhxiy1qv_.js gzip 13.7 kB N/A -
3pchr-7emrys3.js gzip 163 B N/A -
3x-9kf2-gvou9.js gzip 46.6 kB N/A -
41u5s3oe2-erp.js gzip 2.29 kB N/A -
445s_9hf8o7ao.js gzip 8.76 kB N/A -
turbopack-1l..-5yv.js gzip 3.73 kB 3.73 kB ✓
0-6bcj16ji2wf.js gzip N/A 10.6 kB -
05bc8af8ar0hm.js gzip N/A 157 B -
07ryk0jced-sc.js gzip N/A 8.78 kB -
0ehfrsq4t9oxv.js gzip N/A 157 B -
0fcqiazz8rrj6.js gzip N/A 169 B -
0jwho9fkrb_t3.js gzip N/A 2.29 kB -
0kggekbduqh7_.js gzip N/A 46.6 kB -
0roh390ijzxa5.js gzip N/A 8.75 kB -
0ryyb26nk8l4-.js gzip N/A 65.6 kB -
0vex9w55ursqj.js gzip N/A 8.79 kB -
17oe55cu76cd7.js gzip N/A 450 B -
1drww5xikb-c-.js gzip N/A 9.46 kB -
1f0sbbzbtb8-d.js gzip N/A 156 B -
1g60xde_dv17t.js gzip N/A 8.79 kB -
1hfawbaxawa1b.js gzip N/A 156 B -
1uzv47btzam64.js gzip N/A 5.73 kB -
1vy7n7wxv_rh5.js gzip N/A 8.81 kB -
2-0i7pl900-ou.js gzip N/A 8.71 kB -
2-kcbngm7ik7y.js gzip N/A 8.75 kB -
24xppfz7hzt_u.js gzip N/A 161 B -
29p5-xa4jmdhg.js gzip N/A 13.7 kB -
2kgg_yiaz8rd6.js gzip N/A 155 B -
2lpk5_hknut8q.js gzip N/A 13.1 kB -
2o4cibp3awtbw.js gzip N/A 3.56 kB -
2ugc69z0t0ypz.js gzip N/A 1.46 kB -
2ysmo6k0h552j.js gzip N/A 156 B -
31v10264sxw__.js gzip N/A 150 B -
36dn8i-_3dnq5.js gzip N/A 10 kB -
37nj9nluvb6lr.js gzip N/A 157 B -
3a9sn6l54cidw.js gzip N/A 156 B -
3be3-77wi4dm2.js gzip N/A 156 B -
3fljpmwcjxqhx.js gzip N/A 10.3 kB -
3g7d_qk0nyha6.js gzip N/A 158 B -
3gz44skqdlsrb.js gzip N/A 8.71 kB -
3oslhuq9luvp2.js gzip N/A 7.55 kB -
3rsl6m-zn6t_o.js gzip N/A 71.5 kB -
3y9tus7kb5su0.js gzip N/A 13.3 kB -
Total 401 kB 401 kB ⚠️ +2 B

Server

Middleware
Canary PR Change
middleware-b..fest.js gzip 1.06 kB 1.06 kB ✓
Total 1.06 kB 1.06 kB ⚠️ +1 B
Build Details
Build Manifests
Canary PR Change
_buildManifest.js gzip 875 B 876 B ✓
Total 875 B 876 B ⚠️ +1 B
Build Cache
Canary PR Change
00000001.sst gzip 14.6 MB 14 MB 🟢 647 kB (-4%)
00000002.sst gzip 13.5 MB 14.2 MB 🔴 +709 kB (+5%)
00000003.sst gzip 14.7 MB 13.1 MB 🟢 1.63 MB (-11%)
00000004.sst gzip 12.3 MB 14 MB 🔴 +1.65 MB (+13%)
00000005.sst gzip 10.2 MB 10.3 MB 🔴 +67.7 kB (+1%)
00000006.sst gzip 2.81 MB 2.82 MB 🔴 +11.6 kB (+0%)
00000007.sst gzip 59 B 59 B ✓
00000008.meta gzip 89 B 89 B ✓
00000009.meta gzip 298 kB 298 kB ✓
00000010.meta gzip 298 kB 298 kB ✓
00000011.meta gzip 298 kB 298 kB ✓
00000012.sst gzip 51.3 kB 51.5 kB ✓
00000013.sst gzip 1.86 MB 1.86 MB ✓
00000014.sst gzip 59 B 59 B ✓
00000015.meta gzip 116 B 116 B ✓
00000016.meta gzip 325 kB 326 kB ✓
00000017.meta gzip 405 kB 405 kB ✓
00000018.sst gzip 52.1 kB 52.2 kB ✓
00000019.sst gzip 1.38 MB 1.41 MB 🔴 +23.6 kB (+2%)
00000020.sst gzip 59 B 59 B ✓
00000021.meta gzip 116 B 116 B ✓
00000022.meta gzip 325 kB 326 kB ✓
00000023.meta gzip 371 kB 372 kB ✓
00000024.sst gzip 52.2 kB 52.3 kB ✓
00000025.sst gzip 1.38 MB 1.41 MB 🔴 +23.1 kB (+2%)
00000026.sst gzip 59 B 59 B ✓
00000027.meta gzip 116 B 116 B ✓
00000028.meta gzip 325 kB 326 kB ✓
00000029.meta gzip 371 kB 372 kB ✓
00000030.sst gzip 51.5 kB 51.7 kB ✓
00000031.sst gzip 1.38 MB 1.41 MB 🔴 +23.1 kB (+2%)
00000032.sst gzip 59 B 59 B ✓
00000033.meta gzip 116 B 116 B ✓
00000034.meta gzip 325 kB 326 kB ✓
00000035.meta gzip 371 kB 372 kB ✓
00000036.sst gzip 52.1 kB 52.2 kB ✓
00000037.sst gzip 1.38 MB 1.41 MB 🔴 +23.1 kB (+2%)
00000038.sst gzip 59 B 59 B ✓
00000039.meta gzip 116 B 116 B ✓
00000040.meta gzip 325 kB 326 kB ✓
00000041.meta gzip 371 kB 372 kB ✓
CURRENT gzip 24 B 24 B ✓
LOG gzip 660 B 685 B 🔴 +25 B (+4%)
Total 80.3 MB 80.5 MB ⚠️ +264 kB

📦 Webpack

Client

Main Bundles
Canary PR Change
3322-HASH.js gzip 65.7 kB N/A -
4191.HASH.js gzip 169 B N/A -
7920-HASH.js gzip 4.67 kB N/A -
9784-HASH.js gzip 5.63 kB N/A -
b1ad9f4c-HASH.js gzip 63.2 kB N/A -
framework-HASH.js gzip 59.7 kB 59.7 kB ✓
main-app-HASH.js gzip 253 B 254 B ✓
main-HASH.js gzip 40.1 kB 40.1 kB ✓
webpack-HASH.js gzip 1.68 kB 1.68 kB ✓
3577.HASH.js gzip N/A 168 B -
578-HASH.js gzip N/A 66.4 kB -
8590-HASH.js gzip N/A 5.61 kB -
9750-HASH.js gzip N/A 4.68 kB -
a8984546-HASH.js gzip N/A 63.2 kB -
Total 241 kB 242 kB ⚠️ +653 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 193 B ✓
_error-HASH.js gzip 181 B 182 B ✓
css-HASH.js gzip 334 B 331 B ✓
dynamic-HASH.js gzip 1.81 kB 1.81 kB ✓
edge-ssr-HASH.js gzip 255 B 253 B ✓
head-HASH.js gzip 349 B 351 B ✓
hooks-HASH.js gzip 382 B 384 B ✓
image-HASH.js gzip 581 B 582 B ✓
index-HASH.js gzip 260 B 259 B ✓
link-HASH.js gzip 2.48 kB 2.48 kB ✓
routerDirect..HASH.js gzip 317 B 318 B ✓
script-HASH.js gzip 384 B 386 B ✓
withRouter-HASH.js gzip 316 B 315 B ✓
1afbb74e6ecf..834.css gzip 106 B 106 B ✓
Total 7.95 kB 7.96 kB ⚠️ +4 B

Server

Edge SSR
Canary PR Change
edge-ssr.js gzip 129 kB 129 kB ✓
page.js gzip 294 kB 295 kB ✓
Total 423 kB 424 kB ⚠️ +720 B
Middleware
Canary PR Change
middleware-b..fest.js gzip 618 B 615 B ✓
middleware-r..fest.js gzip 156 B 156 B ✓
middleware.js gzip 45.7 kB 45.7 kB ✓
edge-runtime..pack.js gzip 842 B 842 B ✓
Total 47.4 kB 47.4 kB ⚠️ +6 B
Build Details
Build Manifests
Canary PR Change
_buildManifest.js gzip 717 B 718 B ✓
Total 717 B 718 B ⚠️ +1 B
Build Cache
Canary PR Change
0.pack gzip 4.81 MB 4.82 MB 🔴 +6.32 kB (+0%)
index.pack gzip 124 kB 124 kB ✓
index.pack.old gzip 124 kB 123 kB ✓
Total 5.06 MB 5.06 MB ⚠️ +5.61 kB

🔄 Shared (bundler-independent)

Runtimes
Canary PR Change
app-page-exp...dev.js gzip 375 kB 375 kB ✓
app-page-exp..prod.js gzip 207 kB 207 kB ✓
app-page-tur...dev.js gzip 375 kB 375 kB ✓
app-page-tur..prod.js gzip 207 kB 207 kB ✓
app-page-tur...dev.js gzip 371 kB 371 kB ✓
app-page-tur..prod.js gzip 205 kB 205 kB ✓
app-page.run...dev.js gzip 371 kB 371 kB ✓
app-page.run..prod.js gzip 205 kB 205 kB ✓
app-route-ex...dev.js gzip 83.4 kB 85.4 kB 🔴 +2.05 kB (+2%)
app-route-ex..prod.js gzip 56.4 kB 57.9 kB 🔴 +1.51 kB (+3%)
app-route-tu...dev.js gzip 83.4 kB 85.4 kB 🔴 +2.05 kB (+2%)
app-route-tu..prod.js gzip 56.4 kB 57.9 kB 🔴 +1.51 kB (+3%)
app-route-tu...dev.js gzip 83 kB 85 kB 🔴 +2.06 kB (+2%)
app-route-tu..prod.js gzip 56.2 kB 57.7 kB 🔴 +1.52 kB (+3%)
app-route.ru...dev.js gzip 82.9 kB 85 kB 🔴 +2.06 kB (+2%)
app-route.ru..prod.js gzip 56.2 kB 57.7 kB 🔴 +1.52 kB (+3%)
dev-validati...dev.js gzip 133 kB 133 kB ✓
dev-validati...dev.js gzip 133 kB 133 kB ✓
dev-validati...dev.js gzip 131 kB 131 kB ✓
dev-validati...dev.js gzip 131 kB 131 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 46.1 kB 46.1 kB ✓
pages-api-tu..prod.js gzip 34.3 kB 34.3 kB ✓
pages-api.ru...dev.js gzip 46.1 kB 46.1 kB ✓
pages-api.ru..prod.js gzip 34.3 kB 34.3 kB ✓
pages-turbo....dev.js gzip 54.9 kB 54.9 kB ✓
pages-turbo...prod.js gzip 39.9 kB 39.9 kB ✓
pages.runtim...dev.js gzip 54.9 kB 54.9 kB ✓
pages.runtim..prod.js gzip 39.9 kB 39.9 kB ✓
server.runti..prod.js gzip 67 kB 72.1 kB 🔴 +5.17 kB (+8%)
use-cache-pr...dev.js gzip 72.5 kB 72.4 kB ✓
use-cache-pr...dev.js gzip 72.5 kB 72.5 kB ✓
use-cache-pr...dev.js gzip 70.7 kB 70.7 kB ✓
use-cache-pr...dev.js gzip 70.7 kB 70.7 kB ✓
Total 4.11 MB 4.12 MB ⚠️ +19.5 kB
📝 Changed Files (23 files)

Files with changes:

  • app-page-exp..ntime.dev.js
  • app-page-exp..time.prod.js
  • app-page-tur..ntime.dev.js
  • app-page-tur..time.prod.js
  • app-page-tur..ntime.dev.js
  • app-page-tur..time.prod.js
  • app-page.runtime.dev.js
  • app-page.runtime.prod.js
  • app-route-ex..ntime.dev.js
  • app-route-ex..time.prod.js
  • app-route-tu..ntime.dev.js
  • app-route-tu..time.prod.js
  • app-route-tu..ntime.dev.js
  • app-route-tu..time.prod.js
  • app-route.runtime.dev.js
  • app-route.ru..time.prod.js
  • pages-api.ru..time.prod.js
  • pages.runtime.prod.js
  • server.runtime.prod.js
  • use-cache-pr..ntime.dev.js
  • ... and 3 more
View diffs
app-page-exp..ntime.dev.js

Diff too large to display

app-page-exp..time.prod.js

Diff too large to display

app-page-tur..ntime.dev.js

Diff too large to display

app-page-tur..time.prod.js

Diff too large to display

app-page-tur..ntime.dev.js

Diff too large to display

app-page-tur..time.prod.js

Diff too large to display

app-page.runtime.dev.js

Diff too large to display

app-page.runtime.prod.js

Diff too large to display

app-route-ex..ntime.dev.js

Diff too large to display

app-route-ex..time.prod.js

Diff too large to display

app-route-tu..ntime.dev.js

Diff too large to display

app-route-tu..time.prod.js

Diff too large to display

app-route-tu..ntime.dev.js

Diff too large to display

app-route-tu..time.prod.js

Diff too large to display

app-route.runtime.dev.js

Diff too large to display

app-route.ru..time.prod.js

Diff too large to display

pages-api.ru..time.prod.js

Diff too large to display

pages.runtime.prod.js

Diff too large to display

server.runtime.prod.js

Diff too large to display

use-cache-pr..ntime.dev.js

Diff too large to display

use-cache-pr..ntime.dev.js

Diff too large to display

use-cache-pr..ntime.dev.js

Diff too large to display

use-cache-pr..ntime.dev.js

Diff too large to display

📎 Tarball URL 
https://vercel-packages.vercel.app/next/commits/c768b81de786dcafa7c463f427cd85ebf26c1b12/next

Commit: c768b81

@DavidIlie
DavidIlie force-pushed the codex/websocket-route-handlers-hmr branch from bfb9f08 to 77988c3 Compare August 10, 2026 11:34
@DavidIlie
DavidIlie force-pushed the codex/websocket-route-handlers-hmr branch from 77988c3 to feb11ad Compare August 10, 2026 11:40
@DavidIlie
DavidIlie force-pushed the codex/websocket-route-handlers-hmr branch 2 times, most recently from 49c4539 to dc8eea9 Compare August 10, 2026 13:09
@DavidIlie
DavidIlie force-pushed the codex/websocket-route-handlers-hmr branch from dc8eea9 to d993290 Compare August 10, 2026 14:41
@DavidIlie
DavidIlie force-pushed the codex/websocket-route-handlers-hmr branch from d993290 to b29fc22 Compare August 10, 2026 16:29
@DavidIlie
DavidIlie force-pushed the codex/websocket-route-handlers-hmr branch from b29fc22 to c768b81 Compare August 10, 2026 16:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@DavidIlie