offline navigations: register pass-through worker (3/13)

[feedthejim]

Stack Position

This is PR 3/13 in the compressed offline navigations stack. Chapter: Build artifacts and worker boundary.

Review guide: https://gist.github.com/feedthejim/b3d9fe26a7c05655fd57adcce371b93d

Full Stack

1. #93622 offline navigations: add gated build primitives (1/13)
2. #93624 offline navigations: emit fallback manifest data (2/13)
3. #93625 offline navigations: register pass-through worker (3/13) current
4. #93626 offline navigations: cache fallback artifacts (4/13)
5. #93627 offline navigations: serve fallback document offline (5/13)
6. #93630 offline navigations: add persistent navigation cache (6/13)
7. #93631 offline navigations: replay exact-url navigations (7/13)
8. #93635 offline navigations: handle exact-url eligibility and invalidation (8/13)
9. #93640 offline navigations: persist router records (9/13)
10. #93644 offline navigations: hydrate router cache from persisted records (10/13)
11. #93646 offline navigations: reconstruct prefetched routes offline (11/13)
12. #93647 offline navigations: support dynamic route patterns (12/13)
13. #93650 offline navigations: wire invalidation and reset APIs (13/13)

Context

The original offline navigations work was split into 25 staging PRs, which made the review surface too noisy. This compressed stack keeps the same first-usable feature at the tip, but groups the work by reviewer-facing behavior: build artifacts first, exact URL replay next, then route-record replay and invalidation.

The architecture boundary is intentional: the generated service worker keeps the app bootable by serving the fallback document, while the cache-components client router owns IndexedDB, replay eligibility, route reconstruction, visible misses, and invalidation.

Folded source PRs: None.

What This PR Does

• Generates and registers the initial offline-navigation service worker behind the flag.
• Keeps the worker pass-through at this point so registration can be reviewed separately from interception.
• Preserves the architecture boundary: the worker does not route or inspect RSC data.

What Works After This PR

After this PR, an enabled app can register the generated worker without changing navigation semantics.

What Intentionally Does Not Work Yet

The worker does not cache fallback artifacts or serve the fallback document yet.

Reviewer Focus

Registration timing, scope, generated path, pass-through behavior, and keeping the worker free of router semantics.

Proof in This PR

• Focused production e2e passed in Turbopack and webpack modes.
• The suite includes registers the pass-through service worker when enabled.
• git diff --check canary..HEAD passed.
• git diff --stat HEAD f60949e313 and git diff --name-status HEAD f60949e313 produced no output, so the compressed tip preserves the previous staging tip.
• pnpm --filter=next build passed.
• NEXT_TEST_MODE=start pnpm testheadless test/production/app-dir/offline-navigations/offline-navigations.test.ts passed, 12/12.
• IS_WEBPACK_TEST=1 NEXT_TEST_MODE=start pnpm testheadless test/production/app-dir/offline-navigations/offline-navigations.test.ts passed, 12/12.

Deferred Coverage

Install-time caching and navigation fallback handling are deferred.

[github-actions]

Failing test suites

Commit: 7a5e5e9 | About building and testing Next.js

pnpm test-dev-turbo test/development/app-dir/hmr-deleted-page/hmr-deleted-page.test.ts (turbopack) (job)

• hmr-deleted-page > should not show errors for a deleted page (DD)

Expand output

● hmr-deleted-page › should not show errors for a deleted page

Expected no visible Redbox but found one
header: Runtime Error
./app/page/page.tsx:1:1
Module not found: Can't resolve './style.css'
> 1 | import './style.css'
    | ^^^^^^^^^^^^^^^^^^^^
  2 |
  3 | import { Test } from './test'
  4 |



https://nextjs.org/docs/messages/module-not-found
Show More
description: ./app/page/page.tsx:1:1
Module not found: Can't resolve './style.css'
> 1 | import './style.css'
    | ^^^^^^^^^^^^^^^^^^^^
  2 |
  3 | import { Test } from './test'
  4 |



https://nextjs.org/docs/messages/module-not-found
source: null

  25 |     await waitForHydration(browser)
  26 |
> 27 |     await waitForNoRedbox(browser)
     |     ^
  28 |     expect(await browser.elementByCss('h1').text()).toBe('404')
  29 |   })
  30 | })

  at Object.<anonymous> (development/app-dir/hmr-deleted-page/hmr-deleted-page.test.ts:27:5)

[vercel]

Additional Suggestion:

Inline snapshot in next-server-nft test is missing the newly traced /node_modules/next/dist/build/offline-navigation-service-worker.js entry, causing CI test failure.

[github-actions]

Stats from current PR

🔴 1 regression, 1 improvement

Metric	Canary	PR	Change	Trend
node_modules Size	505 MB	505 MB	🔴 +130 kB (+0%)	▁▂▂██
Webpack Build Time	24.171s	23.550s	🟢 621ms (-3%)	▅███▅

📊 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)	814ms	813ms	✓	▅▃▅▇▃
Cold (Ready in log)	788ms	782ms	✓	▂▁▄▅▄
Cold (First Request)	1.271s	1.254s	✓	▂▂▅▆▃
Warm (Listen)	813ms	813ms	✓	▅▃▃█▁
Warm (Ready in log)	786ms	787ms	✓	▂▂▄▃▄
Warm (First Request)	601ms	594ms	✓	▂▃▅▃▄

📦 Dev Server (Webpack) (Legacy)

📦 Dev Server (Webpack)

Metric	Canary	PR	Change	Trend
Cold (Listen)	812ms	810ms	✓	█████
Cold (Ready in log)	790ms	787ms	✓	███▇▇
Cold (First Request)	3.215s	3.163s	✓	▄██▆▄
Warm (Listen)	811ms	810ms	✓	█████
Warm (Ready in log)	786ms	785ms	✓	▇██▇▆
Warm (First Request)	3.213s	3.177s	✓	▃▇█▄▄

⚡ Production Builds

Metric	Canary	PR	Change	Trend
Fresh Build	4.843s	4.922s	✓	▁▁▅█▄
Cached Build	4.865s	4.870s	✓	▁▃▄█▅

📦 Production Builds (Webpack) (Legacy)

📦 Production Builds (Webpack)

Metric	Canary	PR	Change	Trend
Fresh Build	24.171s	23.550s	🟢 621ms (-3%)	▅███▅
Cached Build	23.822s	23.547s	✓	▆▆█▆▄
node_modules Size	505 MB	505 MB	🔴 +130 kB (+0%)	▁▂▂██

📦 Bundle Sizes

Bundle Sizes

⚡ Turbopack

Client

Main Bundles

	Canary	PR	Change
02ffxdsf7jx6t.js gzip	157 B	N/A	-
02xiccz0shdn9.js gzip	49.5 kB	N/A	-
04hm05ar7kldw.js gzip	5.73 kB	N/A	-
06gsfi_m0xcyn.js gzip	161 B	N/A	-
0cz1d0mv5g_q7.js gzip	39.4 kB	39.4 kB	✓
0dvitrl5zg37g.js gzip	8.82 kB	N/A	-
0sf7ysou-72zd.js gzip	8.71 kB	N/A	-
0v8jdh7rfnazz.js gzip	168 B	N/A	-
0vlzv-0h09401.js gzip	157 B	N/A	-
157abun3hwc_s.js gzip	10.3 kB	N/A	-
1elt1qium-r2m.css gzip	115 B	115 B	✓
1jj68jv9537mc.js gzip	13.8 kB	N/A	-
1jpaub6y8xlfr.js gzip	2.3 kB	N/A	-
1m_wvg6gcvtvp.js gzip	153 B	N/A	-
1nxttibwatm2u.js gzip	154 B	N/A	-
1ot0mvscrc_uf.js gzip	233 B	N/A	-
1qtyyb6p_e4gx.js gzip	157 B	N/A	-
1s_pjvrtol87_.js gzip	154 B	N/A	-
2_m3xv2uq3sjc.js gzip	1.46 kB	N/A	-
24y34mwgrkqp4.js gzip	8.78 kB	N/A	-
2c-fd4y1zozz8.js gzip	8.79 kB	N/A	-
2d7416h_xd36x.js gzip	8.71 kB	N/A	-
2extn3odmmem_.js gzip	12.9 kB	N/A	-
2fyhyy7niw9r6.js gzip	7.61 kB	N/A	-
2lyuhit6rn8fy.js gzip	9.44 kB	N/A	-
2mmpp6w4-izb4.js gzip	153 B	N/A	-
2q0gr8wfr3jwl.js gzip	8.77 kB	N/A	-
2siu6f4ud8a_d.js gzip	70.8 kB	N/A	-
2t9e75oz6r0zp.js gzip	8.76 kB	N/A	-
2uku_olcn15b7.js gzip	8.79 kB	N/A	-
2uqsb--492dc1.js gzip	155 B	N/A	-
2vbmj47sfqmzq.js gzip	163 B	N/A	-
30r8mm-46bdqy.js gzip	220 B	220 B	✓
3b5jq4uo44l33.js gzip	153 B	N/A	-
3inab2jybr4k9.js gzip	450 B	N/A	-
3jkm5tdjvaf_q.js gzip	13.1 kB	N/A	-
3jrk4uk0ba4tf.js gzip	155 B	N/A	-
3mt67agm5wp40.js gzip	10.6 kB	N/A	-
3qsii5phyoxm4.js gzip	65.5 kB	N/A	-
3saabek4kohwi.js gzip	10 kB	N/A	-
4189xmby9yu1p.js gzip	13.6 kB	N/A	-
turbopack-02..tg95.js gzip	4.2 kB	N/A	-
turbopack-0g..4wf2.js gzip	4.2 kB	N/A	-
turbopack-0h..e2ij.js gzip	4.2 kB	N/A	-
turbopack-0m..zw9w.js gzip	4.21 kB	N/A	-
turbopack-1-..74jp.js gzip	4.2 kB	N/A	-
turbopack-21..u9gx.js gzip	4.2 kB	N/A	-
turbopack-2f..ag01.js gzip	4.2 kB	N/A	-
turbopack-2r..7z8o.js gzip	4.2 kB	N/A	-
turbopack-30..cuse.js gzip	4.2 kB	N/A	-
turbopack-32..j9tm.js gzip	4.19 kB	N/A	-
turbopack-3k..73s6.js gzip	4.2 kB	N/A	-
turbopack-3w..hhm3.js gzip	4.18 kB	N/A	-
turbopack-3z..s17g.js gzip	4.2 kB	N/A	-
turbopack-3z..ktve.js gzip	4.2 kB	N/A	-
0_i7nqgx23st7.js gzip	N/A	10 kB	-
00ikwr42k-__-.js gzip	N/A	156 B	-
05e40c15cx1dd.js gzip	N/A	7.61 kB	-
06puhytyxk31p.js gzip	N/A	8.82 kB	-
09ublx8mllt2b.js gzip	N/A	156 B	-
0lbxi6fe7sfob.js gzip	N/A	70.8 kB	-
0m34gln_kt4fg.js gzip	N/A	5.73 kB	-
0odav8mrbp0d_.js gzip	N/A	158 B	-
1_-m4_8q25c1t.js gzip	N/A	49.5 kB	-
1g3q1ww01thnl.js gzip	N/A	2.3 kB	-
1hraqxuiymq6v.js gzip	N/A	8.79 kB	-
1l9un1sl77287.js gzip	N/A	1.46 kB	-
1lxerkgn_dyfu.js gzip	N/A	158 B	-
1p5k3-0w6gzt7.js gzip	N/A	153 B	-
1vmnes_3wll3c.js gzip	N/A	156 B	-
21-eavqb1k_36.js gzip	N/A	13.9 kB	-
2147zgtf14z-q.js gzip	N/A	234 B	-
23bz3xsg-5-1s.js gzip	N/A	8.71 kB	-
27441mytv7pbm.js gzip	N/A	9.43 kB	-
2b7huw5v774wp.js gzip	N/A	169 B	-
2cjkwjgm1zcfs.js gzip	N/A	8.71 kB	-
2jgw6-wx5cpt4.js gzip	N/A	161 B	-
2scd8zaoyb8md.js gzip	N/A	8.79 kB	-
2st_qs6p_9us0.js gzip	N/A	13.1 kB	-
2vzmb1tzids9v.js gzip	N/A	159 B	-
2xj1pr8x83eec.js gzip	N/A	155 B	-
2zo2exm1d8qj1.js gzip	N/A	13.6 kB	-
3881z1dii6e92.js gzip	N/A	156 B	-
3gbgjk34zetxr.js gzip	N/A	65.6 kB	-
3hn75zuxly9az.js gzip	N/A	10.3 kB	-
3hqh7m128tvsn.js gzip	N/A	8.77 kB	-
3hqti_t-zy1x4.js gzip	N/A	449 B	-
3mnawenie1flm.js gzip	N/A	8.76 kB	-
3ubsozlu6zs38.js gzip	N/A	10.6 kB	-
3z6tdtry-oasp.js gzip	N/A	155 B	-
41mf-x3mmsxae.js gzip	N/A	12.9 kB	-
42twk6cn4g_is.js gzip	N/A	154 B	-
43iwfqjnx1cy_.js gzip	N/A	8.78 kB	-
turbopack-0n..v3i7.js gzip	N/A	4.2 kB	-
turbopack-0z..iibl.js gzip	N/A	4.2 kB	-
turbopack-1a..wxqm.js gzip	N/A	4.2 kB	-
turbopack-1k..iy2n.js gzip	N/A	4.2 kB	-
turbopack-1t..lhui.js gzip	N/A	4.2 kB	-
turbopack-1y..mujh.js gzip	N/A	4.21 kB	-
turbopack-29..fjt7.js gzip	N/A	4.2 kB	-
turbopack-2b..tnne.js gzip	N/A	4.2 kB	-
turbopack-2g..3kka.js gzip	N/A	4.2 kB	-
turbopack-2g..bysl.js gzip	N/A	4.2 kB	-
turbopack-2i..o69e.js gzip	N/A	4.2 kB	-
turbopack-30..bdvn.js gzip	N/A	4.2 kB	-
turbopack-3f..v-t6.js gzip	N/A	4.2 kB	-
turbopack-3f..p4sf.js gzip	N/A	4.18 kB	-
Total	468 kB	468 kB	⚠️ +76 B

Server

Middleware

	Canary	PR	Change
middleware-b..fest.js gzip	719 B	716 B	✓
Total	719 B	716 B	✅ -3 B

Build Details

Build Manifests

	Canary	PR	Change
_buildManifest.js gzip	433 B	434 B	✓
Total	433 B	434 B	⚠️ +1 B

📦 Webpack

Client

Main Bundles

	Canary	PR	Change
2258-HASH.js gzip	61.1 kB	N/A	-
2266-HASH.js gzip	4.69 kB	N/A	-
3317.HASH.js gzip	169 B	N/A	-
4866-HASH.js gzip	5.64 kB	N/A	-
9e302639-HASH.js gzip	62.7 kB	N/A	-
framework-HASH.js gzip	59.5 kB	59.5 kB	✓
main-app-HASH.js gzip	255 B	254 B	✓
main-HASH.js gzip	39.9 kB	39.9 kB	✓
webpack-HASH.js gzip	1.68 kB	1.68 kB	✓
175fd0fd-HASH.js gzip	N/A	62.7 kB	-
2596-HASH.js gzip	N/A	5.63 kB	-
34-HASH.js gzip	N/A	61 kB	-
5691.HASH.js gzip	N/A	169 B	-
9156-HASH.js gzip	N/A	4.68 kB	-
Total	236 kB	236 kB	✅ -82 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	193 B	193 B	✓
_error-HASH.js gzip	181 B	182 B	✓
css-HASH.js gzip	334 B	332 B	✓
dynamic-HASH.js gzip	1.79 kB	1.81 kB	✓
edge-ssr-HASH.js gzip	255 B	255 B	✓
head-HASH.js gzip	351 B	348 B	✓
hooks-HASH.js gzip	385 B	384 B	✓
image-HASH.js gzip	580 B	580 B	✓
index-HASH.js gzip	257 B	259 B	✓
link-HASH.js gzip	2.51 kB	2.51 kB	✓
routerDirect..HASH.js gzip	318 B	319 B	✓
script-HASH.js gzip	387 B	386 B	✓
withRouter-HASH.js gzip	316 B	316 B	✓
1afbb74e6ecf..834.css gzip	106 B	106 B	✓
Total	7.97 kB	7.98 kB	⚠️ +12 B

Server

Edge SSR

	Canary	PR	Change
edge-ssr.js gzip	126 kB	126 kB	✓
page.js gzip	275 kB	270 kB	🟢 5.27 kB (-2%)
Total	401 kB	396 kB	✅ -5.48 kB

Middleware

	Canary	PR	Change
middleware-b..fest.js gzip	616 B	612 B	✓
middleware-r..fest.js gzip	155 B	155 B	✓
middleware.js gzip	44.4 kB	44.7 kB	✓
edge-runtime..pack.js gzip	842 B	842 B	✓
Total	46.1 kB	46.3 kB	⚠️ +281 B

Build Details

Build Manifests

	Canary	PR	Change
_buildManifest.js gzip	719 B	716 B	✓
Total	719 B	716 B	✅ -3 B

Build Cache

	Canary	PR	Change
0.pack gzip	4.45 MB	4.45 MB	✓
index.pack gzip	114 kB	117 kB	🔴 +2.88 kB (+3%)
index.pack.old gzip	115 kB	116 kB	✓
Total	4.68 MB	4.68 MB	⚠️ +4.63 kB

🔄 Shared (bundler-independent)

Runtimes

	Canary	PR	Change
app-page-exp...dev.js gzip	349 kB	349 kB	✓
app-page-exp..prod.js gzip	194 kB	194 kB	✓
app-page-tur...dev.js gzip	349 kB	349 kB	✓
app-page-tur..prod.js gzip	194 kB	194 kB	✓
app-page-tur...dev.js gzip	345 kB	345 kB	✓
app-page-tur..prod.js gzip	192 kB	192 kB	✓
app-page.run...dev.js gzip	346 kB	346 kB	✓
app-page.run..prod.js gzip	192 kB	192 kB	✓
app-route-ex...dev.js gzip	77.5 kB	77.5 kB	✓
app-route-ex..prod.js gzip	52.9 kB	52.9 kB	✓
app-route-tu...dev.js gzip	77.6 kB	77.6 kB	✓
app-route-tu..prod.js gzip	52.9 kB	52.9 kB	✓
app-route-tu...dev.js gzip	77.2 kB	77.2 kB	✓
app-route-tu..prod.js gzip	52.7 kB	52.7 kB	✓
app-route.ru...dev.js gzip	77.1 kB	77.1 kB	✓
app-route.ru..prod.js gzip	52.7 kB	52.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	44.3 kB	44.3 kB	✓
pages-api-tu..prod.js gzip	33.8 kB	33.8 kB	✓
pages-api.ru...dev.js gzip	44.3 kB	44.3 kB	✓
pages-api.ru..prod.js gzip	33.7 kB	33.7 kB	✓
pages-turbo....dev.js gzip	53.7 kB	53.7 kB	✓
pages-turbo...prod.js gzip	39.4 kB	39.4 kB	✓
pages.runtim...dev.js gzip	53.6 kB	53.6 kB	✓
pages.runtim..prod.js gzip	39.3 kB	39.3 kB	✓
server.runti..prod.js gzip	63.2 kB	63.2 kB	✓
use-cache-pr...dev.js gzip	69.7 kB	69.7 kB	✓
use-cache-pr...dev.js gzip	69.7 kB	69.7 kB	✓
use-cache-pr...dev.js gzip	68 kB	68 kB	✓
use-cache-pr...dev.js gzip	68 kB	68 kB	✓
Total	3.36 MB	3.36 MB	⚠️ +6 B

📝 Changed Files (1 file)

Files with changes:

• server.runtime.prod.js

View diffs

server.runtime.prod.js

Diff too large to display

📎 Tarball URL

https://vercel-packages.vercel.app/next/commits/7a5e5e975c82b63cd7bf6949499c55211944a239/next

Commit: 7a5e5e9