Rewrite instant validation to use depth-based URL boundary discovery by gnoff · Pull Request #90905 · vercel/next.js

gnoff · 2026-03-05T01:33:07Z

Instead of pre-planning validation tasks by walking the tree and accumulating navigationParents, the new implementation drives validation by URL depth. Starting from the deepest URL segment and working backwards, it builds a combined payload at each depth where the boundary between shared (already-mounted) and new (being-navigated-to) content is determined by counting URL-consuming segments. If the new subtree at that depth contains any unstable_instant configs, the payload is validated. If not, it moves to the next shallower depth.

This approach has several advantages over the task-based model:

Route group layouts no longer create spurious navigation boundaries — they don`t consume URL depth, so they naturally share the boundary of their parent URL segment
The requiresInstantUI requirement propagates correctly through the tree: a local false config opts the subtree out, a non-false config opts it in, and no config defers to the OR-union of children slots
Both the static-stage and runtime-retry payloads are built in a single tree walk, avoiding the separate retry pass
The <head> stage correctly uses Runtime when any segment in the new tree uses runtime prefetch

nextjs-bot · 2026-03-05T01:45:41Z

Failing test suites

Commit: 4660de3 | About building and testing Next.js

nextjs-bot · 2026-03-05T01:53:39Z

Stats from current PR

🟢 1 improvement

Metric	Canary	PR	Change	Trend
node_modules Size	477 MB	477 MB	🟢 117 kB (0%)	▁▁▁▁▁

📊 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)	437ms	436ms	✓	▁▁▁▃█
Cold (First Request)	1.219s	1.254s	✓	▁▁▁▃█
Warm (Listen)	457ms	456ms	✓	▁▁▁▅█
Warm (Ready in log)	442ms	442ms	✓	▁▁▁▃█
Warm (First Request)	348ms	349ms	✓	▁▁▁▃█

⚡ Production Builds

Metric	Canary	PR	Change	Trend
Fresh Build	3.817s	3.806s	✓	▁▁▁▃█
Cached Build	3.829s	3.817s	✓	▁▁▁▃█

📦 Production Builds (Webpack) (Legacy)

📦 Production Builds (Webpack)

Metric	Canary	PR	Change	Trend
node_modules Size	477 MB	477 MB	🟢 117 kB (0%)	▁▁▁▁▁

📦 Bundle Sizes

Bundle Sizes

⚡ Turbopack

Client

Main Bundles: **402 kB** → **401 kB** ✅ -30 B

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

Server

Middleware

	Canary	PR	Change
middleware-b..fest.js gzip	767 B	758 B	🟢 9 B (-1%)
Total	767 B	758 B	✅ -9 B

Build Details

Build Manifests

	Canary	PR	Change
_buildManifest.js gzip	449 B	451 B	✓
Total	449 B	451 B	⚠️ +2 B

🔄 Shared (bundler-independent)

Runtimes

	Canary	PR	Change
app-page-exp...dev.js gzip	322 kB	322 kB	✓
app-page-exp..prod.js gzip	171 kB	171 kB	✓
app-page-tur...dev.js gzip	322 kB	322 kB	✓
app-page-tur..prod.js gzip	171 kB	171 kB	✓
app-page-tur...dev.js gzip	318 kB	318 kB	✓
app-page-tur..prod.js gzip	169 kB	169 kB	✓
app-page.run...dev.js gzip	319 kB	319 kB	✓
app-page.run..prod.js gzip	169 kB	169 kB	✓
app-route-ex...dev.js gzip	70.9 kB	70.9 kB	✓
app-route-ex..prod.js gzip	49.3 kB	49.3 kB	✓
app-route-tu...dev.js gzip	70.9 kB	70.9 kB	✓
app-route-tu..prod.js gzip	49.3 kB	49.3 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.ru...dev.js gzip	70.4 kB	70.4 kB	✓
app-route.ru..prod.js gzip	49 kB	49 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.2 kB	43.2 kB	✓
pages-api.ru..prod.js gzip	32.9 kB	32.9 kB	✓
pages-turbo....dev.js gzip	52.6 kB	52.6 kB	✓
pages-turbo...prod.js gzip	38.5 kB	38.5 kB	✓
pages.runtim...dev.js gzip	52.6 kB	52.6 kB	✓
pages.runtim..prod.js gzip	38.5 kB	38.5 kB	✓
server.runti..prod.js gzip	62 kB	62 kB	✓
Total	2.84 MB	2.84 MB	✅ -843 B

📝 Changed Files (4 files)

Files with changes:

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

View diffs

app-page-exp..ntime.dev.js

failed to diff

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

failed to diff

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

failed to diff

app-page.runtime.dev.js

failed to diff

📎 Tarball URL

https://vercel-packages.vercel.app/next/commits/c5599ac93a13c28cc9d9294c4106238fec716eb5/next

packages/next/src/server/app-render/instant-validation/instant-validation.tsx

lubieowoce · 2026-03-05T12:07:29Z

packages/next/src/server/app-render/instant-validation/instant-validation.tsx

+  hasStaticSegments: boolean
+  hasRuntimeSegments: boolean


nit: i would prefer that we either mark the rest as readonly or move these mutable bits into a separate object. at first look ValidationContext seems like a bag of options that gets passed around, it feels confusing to mix mutable state (essentially out-params) into it, like usedSegmentKinds used to be

made it a closure again

wdym? this sounds like it's responding to a different comment

i mean i got rid of Validationcontext. it only existed to extract these closures out into regular functions. but it's not performance critical and just makes the logic a little harder to follow

packages/next/src/server/app-render/app-render.tsx

lubieowoce · 2026-03-05T12:11:56Z

packages/next/src/server/app-render/app-render.tsx

+  const loaderTree = ctx.componentMod.routeModule.userland.loaderTree
+
+  // Only affects a debug environment name label, not functional behavior.
+  const hasRuntimePrefetch = true


We don't expect any new logs thus we don't need the environment name to actually be correct. We can't know globally the right environment anyway because it is actually based on where in the tree you are. I think we can even just get rid of the environment altogether for this re-render pass and have it just return Server or have it return "You shouldn't be seeing this"

hm. i mean, it can end up in stacs that we send to the browser, can it not? like i think you might get SomeComponent [Prerender] in the owner stack

won't it have the original environment name from the original render?

oh right, true, brainfart

packages/next/src/server/app-render/app-render.tsx

packages/next/src/server/app-render/instant-validation/instant-validation.tsx

lubieowoce · 2026-03-05T14:22:55Z

packages/next/src/server/app-render/instant-validation/instant-validation.tsx

+
+  const consumesDepth = segmentConsumesURLDepth(segment)
+
+  if (consumesDepth && urlDepthConsumed === depth) {


i would like some comments explaining how/why this stop condition works, and maybe some examples. it's not obvious for me, i'm guessing i'm not the only one
(also it seems buggy in some cases, DM'd repro)

test/e2e/app-dir/instant-validation/instant-validation.test.ts

Instead of pre-planning validation tasks by walking the tree and accumulating `navigationParents`, the new implementation drives validation by URL depth. Starting from the deepest URL segment and working backwards, it builds a combined payload at each depth where the boundary between shared (already-mounted) and new (being-navigated-to) content is determined by counting URL-consuming segments. If the new subtree at that depth contains any `unstable_instant` configs, the payload is validated. If not, it moves to the next shallower depth. This approach has several advantages over the task-based model: - Route group layouts no longer create spurious navigation boundaries — they don\`t consume URL depth, so they naturally share the boundary of their parent URL segment - The \`requiresInstantUI\` requirement propagates correctly through the tree: a local \`false\` config opts the subtree out, a non-false config opts it in, and no config defers to the OR-union of children slots - Both the static-stage and runtime-retry payloads are built in a single tree walk, avoiding the separate retry pass - The \`<head>\` stage correctly uses Runtime when any segment in the new tree uses runtime prefetch The old task-based implementation (\`findNavigationsToValidate\`, \`validateInstantConfigs\`, etc.) is preserved but no longer called. It will be removed in a follow-up commit.

…90905) Instead of pre-planning validation tasks by walking the tree and accumulating `navigationParents`, the new implementation drives validation by URL depth. Starting from the deepest URL segment and working backwards, it builds a combined payload at each depth where the boundary between shared (already-mounted) and new (being-navigated-to) content is determined by counting URL-consuming segments. If the new subtree at that depth contains any `unstable_instant` configs, the payload is validated. If not, it moves to the next shallower depth. This approach has several advantages over the task-based model: - Route group layouts no longer create spurious navigation boundaries — they don\`t consume URL depth, so they naturally share the boundary of their parent URL segment - The `requiresInstantUI` requirement propagates correctly through the tree: a local `false` config opts the subtree out, a non-false config opts it in, and no config defers to the OR-union of children slots - Both the static-stage and runtime-retry payloads are built in a single tree walk, avoiding the separate retry pass - The `<head>` stage correctly uses Runtime when any segment in the new tree uses runtime prefetch

nextjs-bot added created-by: Next.js team PRs by the Next.js team. tests type: next labels Mar 5, 2026

gnoff requested review from acdlite and lubieowoce March 5, 2026 01:33

acdlite approved these changes Mar 5, 2026

View reviewed changes