router feat: support lazy error component on beforeLoad failures

Current behaviour: if you .lazy() an error component on a beforeLoad, then the error component won't be use and the default one will be instead

Reproduction of current error: https://stackblitz.com/edit/tanstack-router-wiqzauc7?file=src%2Fmain.tsx

Open questions:

I have the following test failing (most likely due to the loading of the lazy component):

 FAIL   @tanstack/react-router  tests/store-updates-during-navigation.test.tsx > Store doesn't update *too many* times during navigation > not found in beforeLoad
AssertionError: expected 8 to be 7 // Object.is equality

- Expected
+ Received

- 7
+ 8

Is that ok to bump to 8 ?

Summary by CodeRabbit

Release Notes

Bug Fixes
- Enhanced error handling flow to ensure route resources are properly loaded before error processing
- Improved support for lazy-loaded error components across router implementations

Oct 21 '25 15:10 beaussan

Walkthrough

Multiple test files are restructured to support lazy error component testing through a new parameterization flag. The error handling in load-matches.ts is modified to ensure route chunks load before error processing. A formatting line is added to useNavigate.tsx.

Changes

Cohort / File(s)	Change Summary
Formatting `packages/react-router/src/useNavigate.tsx`	Added blank line after import type block.
Lazy Error Component Tests `packages/react-router/tests/errorComponent.test.tsx`, `packages/solid-router/tests/errorComponent.test.tsx`	Introduced `isUsingLazyError` parameterization wrapper around existing error component tests; routes now conditionally use `lazy()` with `createLazyRoute` to supply error components when `isUsingLazyError = true`; adjusted timeouts for lazy-loading delays.
Error Handling Flow `packages/router-core/src/load-matches.ts`	Modified `executeBeforeLoad` error handling to await `loadRouteChunk(route)` before invoking `handleSerialError`, ensuring route chunks load prior to error processing.

Sequence Diagram(s)

sequenceDiagram
    participant App
    participant executeBeforeLoad
    participant Chunk as loadRouteChunk
    participant Error as handleSerialError
    
    App->>executeBeforeLoad: Begin before load
    executeBeforeLoad->>executeBeforeLoad: Execute route logic
    
    rect rgb(200, 220, 255)
        Note over executeBeforeLoad,Error: On Error (New Flow)
        executeBeforeLoad->>Chunk: Await load route chunk
        Chunk-->>executeBeforeLoad: Chunk loaded
        executeBeforeLoad->>Error: Handle error with chunk ready
    end
    
    Error-->>App: Error handled

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

The changes mix formatting updates, substantial test restructuring with new lazy-loading patterns across two test files, and focused error-handling logic modifications. The heterogeneity of changes and test complexity warrant moderate review effort despite homogeneous patterns within test parameterizations.

Possibly related PRs

#4961: Modifies executeBeforeLoad and error handling in load-matches.ts to ensure route chunks load before serial error processing—directly related to the error handling changes.
#4971: Also modifies executeBeforeLoad and error-handling flow in load-matches.ts with similar chunk-loading-before-error-handling logic.
#4993: Refactors beforeLoad execution and skip logic, relating to the overall control-flow adjustments in executeBeforeLoad.

Suggested reviewers

Sheraff
nlynzaad
schiller-manuel

Poem

🐰 Lazy chunks now load before errors appear,
Tests wrap in parameters, the path becomes clear!
Error handling flows with a promise in hand,
While React and Solid dance across the land. ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring 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 (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The PR title "feat: support lazy error component on beforeLoad failures" directly aligns with the main objective stated in the pull request, which is to add support for using a lazily loaded error component when a route's beforeLoad handler fails. The title accurately summarizes the primary feature being implemented across the changeset, including the key behavioral change in `load-matches.ts` and the corresponding test updates in both react-router and solid-router packages. The title is specific, clear, and avoids vague terminology, making it immediately understandable to someone reviewing the commit history.

✨ Finishing touches

[ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

[ ] Create PR with unit tests
[ ] Post copyable unit tests in a comment

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Oct 21 '25 15:10 coderabbitai[bot]

🤖 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.}

View your CI Pipeline Execution ↗ for commit 52e8c8b5afd4a2d3d0b9954450b0ce8bc24ab822

Command	Status	Duration	Result
`nx affected --targets=test:eslint,test:unit,tes...`	❌ Failed	7m 33s	View ↗
`nx run-many --target=build --exclude=examples/*...`	✅ Succeeded	1m 24s	View ↗

☁️ Nx Cloud last updated this comment at 2025-11-19 23:11:23 UTC

Oct 21 '25 15:10 nx-cloud[bot]

More templates

@tanstack/arktype-adapter

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

@tanstack/directive-functions-plugin

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

@tanstack/eslint-plugin-router

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/server-functions-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/zod-adapter

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

commit: 52e8c8b

Oct 21 '25 16:10 pkg-pr-new[bot]

Is that ok to bump to 8 ?

Yes that seems good

Oct 23 '25 10:10 Sheraff

Yes that seems good

Great, thanks! Then I guess the pr is good to go from my point of view

Oct 23 '25 10:10 beaussan

Then I guess the pr is good to go from my point of view

I do think we should at least make sure not to load the components if it's throwing a redirect.

Oct 23 '25 11:10 Sheraff

I do think we should at least make sure not to load the components if it's throwing a redirect.

Done

Oct 27 '25 09:10 beaussan