Skip to content
Source
Sign inSign up
TanStack/router

fix: serial head execution #6093

Mergedschiller-manuel(GitHub profile, opens in a new tab)merged 6 commits intomain fromrefs/pull/6093/headmerged by schiller-manuel(GitHub profile, opens in a new tab)

fixes #6085 fixes #4785 fixes #4889

Summary by CodeRabbit

  • Bug Fixes
    • Router waits for all loaders to settle, defers applying head metadata until after loaders complete, logs head errors without stopping other heads, and improves redirect and 404 handling.
  • Chores
    • Removed the not-found "via-head" route and its UI links; removed related prerender exclusion entries.
  • Tests
    • E2E not-found tests narrowed to loader-only thrower scenarios (removed head thrower).
✏️ Tip: You can customize this high-level summary in your review settings.
    1. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-core

    2. Walkthrough

      Defer route head execution until after all loader Promises settle (use Promise.allSettled). Run heads serially with guarded try/catch, surface redirects immediately after loaders settle, and throw notFound errors after head processing. Removed file-based via-head not-found routes and updated related tests and prerender filters.

      Changes

      Cohort / File(s)Summary
      Router core — load/heads coordination
      packages/router-core/src/load-matches.ts
      Replaced Promise.all with Promise.allSettled for loader Promises; removed inline head execution during loader runs; added a post-settle serial executeHead pass that applies head metadata with try/catch; detect and throw redirects immediately after settle; throw first notFound after head pass; improved error logging and ensured loader errors don't block other heads.
      Removed not-found routes (React / Solid / Vue)
      e2e/react-start/basic/src/routes/not-found/via-head.tsx, e2e/solid-start/basic/src/routes/not-found/via-head.tsx, e2e/vue-start/basic/.../src/routes/not-found/via-head.tsx
      Deleted file-based "via-head" not-found route files, their exported Route declarations, head handlers, notFoundComponent, and route components.
      Route tree & generated types
      e2e/react-start/basic/src/routeTree.gen.ts, e2e/solid-start/basic/src/routeTree.gen.ts, e2e/vue-start/basic/src/routeTree.gen.ts
      Removed imports, route definitions, type entries, and module-augmentation entries for /not-found/via-head across generated route maps and types.
      Not-found pages — UI links removed
      e2e/react-start/basic/src/routes/not-found/index.tsx, e2e/solid-start/basic/src/routes/not-found/index.tsx, e2e/vue-start/basic/src/routes/not-found/index.tsx
      Removed Link/UI block that pointed to ./via-head from not-found index pages.
      E2E tests — reduced thrower matrix
      e2e/react-start/basic/tests/not-found.spec.ts, e2e/solid-start/basic/tests/not-found.spec.ts, e2e/vue-start/basic/tests/not-found.spec.ts
      Removed 'head' from thrower scenarios in navigation and direct-visit test matrices (left 'loader' only).
      Prerender configuration changes
      e2e/react-start/basic/vite.config.ts, e2e/solid-start/basic/vite.config.ts, e2e/vue-start/basic/vite.config.ts
      Removed /not-found/via-head from prerender exclusion filters.

      Sequence Diagram(s)

      sequenceDiagram
          autonumber
          actor Client
          participant LoadMatches as LoadMatches
          participant Loaders as LoaderPool
          participant HeadExec as HeadExecutor
          participant Inspector as ErrorInspector
      
          Client->>LoadMatches: loadMatches(request)
          LoadMatches->>Loaders: start all loaders in parallel
          par loaders run
              Loaders->>Loaders: each loader resolves/rejects
          end
          note right of Loaders: Promise.allSettled collects results
      
          LoadMatches->>Inspector: inspect settled results for Redirects
          alt redirect found
              Inspector-->>Client: throw Redirect (exit, skip heads)
          else no redirect
              LoadMatches->>HeadExec: executeHead(match) serially per match
              HeadExec-->>LoadMatches: apply head metadata (try/catch per head)
              LoadMatches->>Inspector: inspect settled results for notFound
              alt notFound found
                  Inspector-->>Client: throw first notFound
              else
                  LoadMatches-->>Client: return loaded matches with head applied
              end
          end

      Estimated code review effort

      🎯 4 (Complex) | ⏱️ ~45 minutes

      • TanStack/router#4961 — Modifies router-core's loadMatches/loader/head execution flow (related sequencing/refactor).
      • TanStack/router#4967 — Changes loader/head orchestration in packages/router-core/src/load-matches.ts.
      • TanStack/router#4971 — Adjusts loadMatches and head timing; touches the same core file.

      Suggested reviewers

      • nlynzaad

      Pre-merge checks and finishing touches

      ❌ Failed checks (1 warning)
      Check nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.You can run @coderabbitai generate docstrings to improve docstring coverage.
      ✅ Passed checks (4 passed)
      Check nameStatusExplanation
      Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
      Title check✅ PassedThe title 'fix: serial head execution' directly describes the main change: moving head execution to a post-loader serial phase instead of inline execution.
      Linked Issues check✅ PassedChanges address #6085 by ensuring head runs after all loaders settle, enabling notFound pages to include head data even with async root loaders. Changes ensure head access to matched routes' context for #4785 and #4889 by deferring head execution until all loader context is available.
      Out of Scope Changes check✅ PassedChanges are scoped to head execution timing and test updates; removed test routes (via-head) and updated test matrices are necessary to support the serial head execution model and remove incompatible test scenarios.
      ✨ Finishing touches
      • 📝 Generate docstrings
        🧪 Generate unit tests (beta)
      • Create PR with unit tests
      • Post copyable unit tests in a comment
      • Commit unit tests in branch `serial-head-execution`

      📜 Recent review details

      Configuration used: defaults

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between 87908f3e5295bae03182964a22813c99073cc135 and 815e77b06eb40410189cc2a46c73952821ca6d9b.

      📒 Files selected for processing (1)
      • packages/router-core/src/load-matches.ts
      🧰 Additional context used
      📓 Path-based instructions (2)
      **/*.{ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use TypeScript strict mode with extensive type safety for all code

      Files:

      • packages/router-core/src/load-matches.ts
      **/*.{js,ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Implement ESLint rules for router best practices using the ESLint plugin router

      Files:

      • packages/router-core/src/load-matches.ts
      🧠 Learnings (3)
      📚 Learning: 2025-12-21T12:52:35.231Z
      Learnt from: Sheraff
      Repo: TanStack/router PR: 6171
      File: packages/router-core/src/new-process-route-tree.ts:898-898
      Timestamp: 2025-12-21T12:52:35.231Z
      Learning: In `packages/router-core/src/new-process-route-tree.ts`, the matching logic intentionally allows paths without trailing slashes to match index routes with trailing slashes (e.g., `/a` can match `/a/` route), but not vice-versa (e.g., `/a/` cannot match `/a` layout route). This is implemented via the condition `!pathIsIndex || node.kind === SEGMENT_TYPE_INDEX` and is a deliberate design decision to provide better UX by being permissive with missing trailing slashes.

      Applied to files:

      • packages/router-core/src/load-matches.ts
      📚 Learning: 2025-10-08T08:11:47.088Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5402
      File: packages/router-generator/tests/generator/no-formatted-route-tree/routeTree.nonnested.snapshot.ts:19-21
      Timestamp: 2025-10-08T08:11:47.088Z
      Learning: Test snapshot files in the router-generator tests directory (e.g., files matching the pattern `packages/router-generator/tests/generator/**/routeTree*.snapshot.ts` or `routeTree*.snapshot.js`) should not be modified or have issues flagged, as they are fixtures used to verify the generator's output and are intentionally preserved as-is.

      Applied to files:

      • packages/router-core/src/load-matches.ts
      📚 Learning: 2025-10-01T18:30:26.591Z
      Learnt from: schiller-manuel
      Repo: TanStack/router PR: 5330
      File: packages/router-core/src/router.ts:2231-2245
      Timestamp: 2025-10-01T18:30:26.591Z
      Learning: In `packages/router-core/src/router.ts`, the `resolveRedirect` method intentionally strips the router's origin from redirect URLs when they match (e.g., `https://foo.com/bar` → `/bar` for same-origin redirects) while preserving the full URL for cross-origin redirects. This logic should not be removed or simplified to use `location.publicHref` directly.

      Applied to files:

      • packages/router-core/src/load-matches.ts
      ⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
      • GitHub Check: Preview
      • GitHub Check: Test
      🔇 Additional comments (2)
      packages/router-core/src/load-matches.ts (2)

      900-920: LGTM! Correct approach for deferred error handling.

      The switch from Promise.all to Promise.allSettled is essential for allowing all loaders to complete before executing heads. The logic correctly differentiates between redirects (thrown immediately) and notFound errors (deferred until after head execution), which aligns with the PR objectives.


      942-945: LGTM! Correctly defers notFound to allow head emission.

      Throwing notFound after head execution ensures that head data (CSS, meta tags, etc.) is available before the error is thrown. This directly addresses the PR objective to ensure not-found pages include head output.


      Comment `@coderabbitai help` to get the list of available commands and usage tips.
    3. 🤖 Nx Cloud AI Fix Eligible

      An automatically generated fix could have helped fix failing tasks for this run, but Self-healing CI is disabled for this workspace. Visit workspace settings to enable it and get automatic fixes in future runs.

      To disable these notifications, a workspace admin can disable them [in workspace settings.](https://cloud.nx.app/orgs/6412ca9d1c251d000efa21ba/workspaces/6442f7de8226a6291646a813/settings/self-healing-ci?utm_source=pull-request&utm_medium=comment)

      View your CI Pipeline Execution ↗ for commit 815e77b06eb40410189cc2a46c73952821ca6d9b

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...❌ Failed9m 59sView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded1m 41sView ↗

      ☁️ Nx Cloud last updated this comment at 2025-12-23 01:54:21 UTC

    4. Actionable comments posted: 0

      🧹 Nitpick comments (2)
      packages/router-core/src/load-matches.ts (2)

      917-933: Consider limiting head execution to successfully loaded matches.

      The loop iterates over all inner.matches, but loaders only execute for matches up to inner.firstBadMatchIndex (line 896-898). Matches beyond this index may have incomplete state (no loader data), which could cause unexpected behavior in head functions that depend on loaderData.

      Consider aligning the head execution range with the loader execution range:

      -    for (const match of inner.matches) {
      +    const headMax = inner.firstBadMatchIndex ?? inner.matches.length
      +    for (let i = 0; i < headMax; i++) {
      +      const match = inner.matches[i]!
             const { id: matchId, routeId } = match

      Alternatively, if executing heads for all matches is intentional (even failed ones), please add a comment clarifying this design choice.


      916-916: Address TODO: decide on head execution failure behavior.

      The current implementation continues executing other head functions when one fails, which is resilient but may mask issues in development. Consider documenting the chosen behavior or removing the TODO if the current approach is final.

      Would you like me to open an issue to track this decision, or is the current continue-on-failure behavior the intended final design?

      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between 85bf22e57813a3fc582866fb3b6bf39aec31dc94 and aca0594e82df8bc2bb87aebeab6a962f323abe0c.

      📒 Files selected for processing (1)
      • packages/router-core/src/load-matches.ts (1 hunks)
      🧰 Additional context used
      📓 Path-based instructions (2)
      **/*.{ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use TypeScript strict mode with extensive type safety for all code

      Files:

      • packages/router-core/src/load-matches.ts
      **/*.{js,ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Implement ESLint rules for router best practices using the ESLint plugin router

      Files:

      • packages/router-core/src/load-matches.ts
      🧬 Code graph analysis (1)
      packages/router-core/src/load-matches.ts (1)
      packages/router-core/src/index.ts (2)
      • isRedirect (368-368)
      • isNotFound (374-374)
      ⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
      • GitHub Check: Test
      • GitHub Check: Preview
      🔇 Additional comments (3)
      packages/router-core/src/load-matches.ts (3)

      900-905: LGTM - Promise.allSettled usage is appropriate here.

      Using Promise.allSettled ensures all loaders complete before processing results, which aligns with the goal of deferring head execution until all loaders settle. The failure extraction logic is correct.


      907-912: Redirect early-exit logic is correct.

      Throwing on the first redirect before head execution is the right approach - there's no need to compute head metadata when redirecting.


      935-940: NotFound handling after head execution is appropriate.

      The asymmetry with redirect handling (redirect throws before head, notFound throws after head) is intentional and makes sense - a notFound page can still benefit from head metadata, while a redirect doesn't need any rendering.

    5. More templates

      @tanstack/arktype-adapter

      npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@6093

      @tanstack/directive-functions-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@6093

      @tanstack/eslint-plugin-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@6093

      @tanstack/history

      npm i https://pkg.pr.new/TanStack/router/@tanstack/history@6093

      @tanstack/nitro-v2-vite-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@6093

      @tanstack/react-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@6093

      @tanstack/react-router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@6093

      @tanstack/react-router-ssr-query

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@6093

      @tanstack/react-start

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@6093

      @tanstack/react-start-client

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@6093

      @tanstack/react-start-server

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@6093

      @tanstack/router-cli

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@6093

      @tanstack/router-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@6093

      @tanstack/router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@6093

      @tanstack/router-devtools-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@6093

      @tanstack/router-generator

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@6093

      @tanstack/router-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@6093

      @tanstack/router-ssr-query-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@6093

      @tanstack/router-utils

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@6093

      @tanstack/router-vite-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@6093

      @tanstack/server-functions-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@6093

      @tanstack/solid-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@6093

      @tanstack/solid-router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@6093

      @tanstack/solid-router-ssr-query

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-ssr-query@6093

      @tanstack/solid-start

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@6093

      @tanstack/solid-start-client

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@6093

      @tanstack/solid-start-server

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@6093

      @tanstack/start-client-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@6093

      @tanstack/start-fn-stubs

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-fn-stubs@6093

      @tanstack/start-plugin-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@6093

      @tanstack/start-server-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@6093

      @tanstack/start-static-server-functions

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@6093

      @tanstack/start-storage-context

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@6093

      @tanstack/valibot-adapter

      npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@6093

      @tanstack/virtual-file-routes

      npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@6093

      @tanstack/vue-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router@6093

      @tanstack/vue-router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-devtools@6093

      @tanstack/vue-router-ssr-query

      npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-router-ssr-query@6093

      @tanstack/vue-start

      npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start@6093

      @tanstack/vue-start-client

      npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-client@6093

      @tanstack/vue-start-server

      npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-server@6093

      @tanstack/zod-adapter

      npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@6093

      commit: 815e77b

    6. packages/router-core/src/load-matches.ts lines 935 to 940Outdated
      @@ -934,0 +920,21 @@
      920+ try {
      921+ const headResult = executeHead(inner, matchId, route)
      922+ if (headResult) {
      923+ const head = await headResult
      924+ inner.updateMatch(matchId, (prev) => ({
      925+ ...prev,
      926+ ...head,
      927+ }))
      928+ }
      929+ } catch (err) {
      930+ // Log error but continue executing other head functions
      931+ console.error(`Error executing head for route ${routeId}:`, err)
      932+ }
      933+ }
      934+
      935+ // After head execution, check for notFound errors and throw the first one
      936+ for (const err of failures) {
      937+ if (isNotFound(err)) {
      938+ throw err
      939+ }
      940+ }

      I find it a little curious that we call executeHead for children of a match that would have thrown a notFound

      If we have /a/b/c and /b throws a notFound it its loader, should we really still execute the head of /c? It feels "leaky"

    7. Actionable comments posted: 1

      ♻️ Duplicate comments (1)
      e2e/solid-start/basic/tests/not-found.spec.ts (1)

      29-29: Verify consistency: 'head' removed from navigation tests but retained in direct visit tests.

      This file has the same inconsistency as the React Start test file. The enriched summary indicates that the via-head route file was removed, yet line 61 still includes 'head' in the directVisitTestMatrix. This will cause test failures when the direct visit test attempts to navigate to /not-found/via-head.

      Given that this PR addresses head execution issues with notFound() (PR objectives #6085), removing test coverage for navigation scenarios where notFound is thrown from head() appears inconsistent with the PR's goals.

      📜 Review details

      Configuration used: defaults

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between aca0594e82df8bc2bb87aebeab6a962f323abe0c and 921730e138ba90f991d718e4a0c3ff1cf16f8f61.

      📒 Files selected for processing (4)
      • e2e/react-start/basic/src/routes/not-found/via-head.tsx
      • e2e/react-start/basic/tests/not-found.spec.ts
      • e2e/solid-start/basic/src/routes/not-found/via-head.tsx
      • e2e/solid-start/basic/tests/not-found.spec.ts
      💤 Files with no reviewable changes (2)
      • e2e/solid-start/basic/src/routes/not-found/via-head.tsx
      • e2e/react-start/basic/src/routes/not-found/via-head.tsx
      🧰 Additional context used
      📓 Path-based instructions (2)
      **/*.{ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use TypeScript strict mode with extensive type safety for all code

      Files:

      • e2e/solid-start/basic/tests/not-found.spec.ts
      • e2e/react-start/basic/tests/not-found.spec.ts
      **/*.{js,ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Implement ESLint rules for router best practices using the ESLint plugin router

      Files:

      • e2e/solid-start/basic/tests/not-found.spec.ts
      • e2e/react-start/basic/tests/not-found.spec.ts
      🧠 Learnings (3)
      📚 Learning: 2025-10-09T12:59:02.129Z
      Learnt from: hokkyss
      Repo: TanStack/router PR: 5418
      File: e2e/react-start/custom-identifier-prefix/src/styles/app.css:19-21
      Timestamp: 2025-10-09T12:59:02.129Z
      Learning: In e2e test directories (paths containing `e2e/`), accessibility concerns like outline suppression patterns are less critical since the code is for testing purposes, not production use.

      Applied to files:

      • e2e/solid-start/basic/tests/not-found.spec.ts
      • e2e/react-start/basic/tests/not-found.spec.ts
      📚 Learning: 2025-10-08T08:11:47.088Z
      Learnt from: nlynzaad
      Repo: TanStack/router PR: 5402
      File: packages/router-generator/tests/generator/no-formatted-route-tree/routeTree.nonnested.snapshot.ts:19-21
      Timestamp: 2025-10-08T08:11:47.088Z
      Learning: Test snapshot files in the router-generator tests directory (e.g., files matching the pattern `packages/router-generator/tests/generator/**/routeTree*.snapshot.ts` or `routeTree*.snapshot.js`) should not be modified or have issues flagged, as they are fixtures used to verify the generator's output and are intentionally preserved as-is.

      Applied to files:

      • e2e/solid-start/basic/tests/not-found.spec.ts
      • e2e/react-start/basic/tests/not-found.spec.ts
      📚 Learning: 2025-10-09T12:59:14.842Z
      Learnt from: hokkyss
      Repo: TanStack/router PR: 5418
      File: e2e/react-start/custom-identifier-prefix/public/site.webmanifest:2-3
      Timestamp: 2025-10-09T12:59:14.842Z
      Learning: In e2e test fixtures (files under e2e directories), empty or placeholder values in configuration files like site.webmanifest are acceptable and should not be flagged unless the test specifically validates those fields.

      Applied to files:

      • e2e/solid-start/basic/tests/not-found.spec.ts
      • e2e/react-start/basic/tests/not-found.spec.ts
      ⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
      • GitHub Check: Preview
      • GitHub Check: Test
      Resolvedby coderabbitai[bot](GitHub profile, opens in a new tab)

Sign in to join this conversation.