refactor(router-plugin): Build-time route matching #4714

Sheraff · 2025-07-19T11:35:17Z

Performance of matchByPath (router-core > path) can be improved by generating a "pre-compiled" route matching function at build-time

nx-cloud · 2025-07-19T11:35:40Z

🤖 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 82fb6dc

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

☁️ Nx Cloud last updated this comment at 2025-08-24 22:10:36 UTC

pkg-pr-new · 2025-07-19T11:38:16Z

More templates

@tanstack/arktype-adapter

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

@tanstack/directive-functions-plugin

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

@tanstack/eslint-plugin-router

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

@tanstack/history

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-plugin

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/server-functions-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-plugin

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-server-functions-client

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

@tanstack/start-server-functions-fetcher

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

@tanstack/start-server-functions-server

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/zod-adapter

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

commit: 82fb6dc

We noticed that `parsePathname` is a performance bottleneck during navigation events. Here's a flamegraph from an application w/ ~300 routes around a navigation event: <img width="853" height="372" alt="Screenshot 2025-07-22 at 19 36 24" src="https://github.com/user-attachments/assets/7ed2e09a-8ea9-4170-862a-2d53c3eb4793" /> This PR proposes a basic least-recently-used cache implementation (that data structure is about 4-5x slower than a `Map` according to benchmarks, and it uses a little more memory). We can add caching to `parsePathname` now that what it returns is readonly (#4705), which should improve the performance of this bottleneck. The cache is set to a size of 1000. When / if we end up making a pre-built matcher (WIP #4714), we maybe can reduce this size. But `parsePathname` is still called w/ built pathnames so we probably shouldn't remove the cache entirely. When benchmarking `matchPathname` with and without the cache, we notice a ~9x increase in throughput with the cache. ``` ✓ @tanstack/router-core tests/cache.bench.ts > cache.bench 7191ms name hz min max mean p75 p99 p995 p999 rme samples · original 1,795.61 0.5055 0.7022 0.5569 0.5604 0.6234 0.6464 0.7022 ±0.22% 898 · cached 16,307.87 0.0562 0.2294 0.0613 0.0608 0.0767 0.1007 0.1152 ±0.17% 8154 fastest BENCH Summary @tanstack/router-core cached - tests/cache.bench.ts > cache.bench 9.08x faster than original ``` Assuming this 9x increase translates to a proportional reduction of the self-time seen in the flamegraph, it would go from 55ms to 6ms.

coderabbitai · 2025-08-16T12:13:50Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing Touches

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch router-core-build-time-route-matcher

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

Visit our Status Page to check the current availability of CodeRabbit.
Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

feat(router-plugin) Build-time route matching

63200f6

github-actions bot added the package: router-core label Jul 19, 2025

ci: apply automated fixes

a72186e

Sheraff and others added 4 commits July 19, 2025 14:06

fix depth iteration issue

02ccf64

better leaf conditions

90ae082

ci: apply automated fixes

a66b79f

2 more cases

5f0b327

Sheraff changed the title ~~feat(router-plugin) Build-time route matching~~ refactor(router-plugin): Build-time route matching Jul 19, 2025

Sheraff added 6 commits July 19, 2025 19:45

test setup now shows actual results

1eb8ce5

can condense multiple depths in a single if

0d19c8b

prettier

3251741

rename stuff

7890c3f

dynamic params

af589e5

prettier

6e9c361

Sheraff force-pushed the router-core-build-time-route-matcher branch from fe2e83e to 6e9c361 Compare July 19, 2025 22:05

Sheraff and others added 7 commits July 20, 2025 00:59

support for wildcard

6799fcb

prettier

c74a36a

root route

e40ccbd

ci: apply automated fixes

adba433

fix route rebuilding

e5501fb

recursion preserves order

a5eb6c6

alternate implementation

7d2b299

Sheraff force-pushed the router-core-build-time-route-matcher branch from e0fb7e3 to 7d2b299 Compare July 20, 2025 09:05

better condition grouping

31700cb

Sheraff force-pushed the router-core-build-time-route-matcher branch from 97d0fde to 31700cb Compare July 20, 2025 09:20

Sheraff added 3 commits July 20, 2025 12:26

skip length check if constraint applies to all children

80e3343

reduce array access

0adb157

add rank conditions

d3712b4

Sheraff added 27 commits July 23, 2025 12:29

Merge branch 'main' into router-core-build-time-route-matcher

a716491

support runtime fuzzy options

844df5e

fix level 0 grouping

b4f7d74

cleanup

7391bad

support case insensitive maatching

173ad09

code comments

50635c5

productize

99678b5

cleanup

f282ab2

missing export

ec6e4dc

rename file

ead4795

rename

4e64eb1

better comments and naming

f9e0740

case sensitivity applies to all parts, not just static pathnames

c6617f7

reduce accessor complexity

9460511

add a tree pruning step

c89f87d

typo

0f5402a

add bench

7ca2c40

add compiled-matcher E2E project

d4bc4a5

prettier

0356bc7

add unit test for optional param followed by regular param

7ae9b8a

Merge branch 'main' into router-core-build-time-route-matcher

c6d5ca2

improve tree pruning

b8f9dd1

simplify tree pruning

c86a84f

add optional+regular param test case to benchmark

2858cfa

add code comment for possible pruning improvement

99a98f9

add another benchmark for single lookup

a2f0f17

Merge branch 'main' into router-core-build-time-route-matcher

00a56ff

Merge branch 'main' into router-core-build-time-route-matcher

82fb6dc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

refactor(router-plugin): Build-time route matching #4714

refactor(router-plugin): Build-time route matching #4714

Uh oh!

Sheraff commented Jul 19, 2025

Uh oh!

nx-cloud bot commented Jul 19, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jul 19, 2025 •

edited

Loading

Uh oh!

coderabbitai bot commented Aug 16, 2025

Review skipped

Chat

Support

CodeRabbit Commands (Invoked using PR/Issue comments)

Other keywords and placeholders

CodeRabbit Configuration File (`.coderabbit.yaml`)

Status, Documentation and Community

Uh oh!

Uh oh!

Uh oh!

refactor(router-plugin): Build-time route matching #4714

Are you sure you want to change the base?

refactor(router-plugin): Build-time route matching #4714

Uh oh!

Conversation

Sheraff commented Jul 19, 2025

Uh oh!

nx-cloud bot commented Jul 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 Nx Cloud AI Fix Eligible

Uh oh!

pkg-pr-new bot commented Jul 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Aug 16, 2025

Review skipped

Chat

Support

CodeRabbit Commands (Invoked using PR/Issue comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Status, Documentation and Community

Uh oh!

Uh oh!

nx-cloud bot commented Jul 19, 2025 •

edited

Loading

pkg-pr-new bot commented Jul 19, 2025 •

edited

Loading

CodeRabbit Configuration File (`.coderabbit.yaml`)