Add a comprehensive migration guide from React Router v7 to TanStack
Router, addressing feedback to target the latest version.
The original PR #4704 aimed to provide a migration guide from React
Router v6. However, a comment from schiller-manuel questioned why v6 was
targeted instead of v7. This PR updates the scope to focus on React
Router v7, which was released in November 2024 and is the current
version, ensuring the guide is relevant for users migrating from the
latest React Router.
---
[Open in
Web](https://cursor.com/agents?id=bc-035967dd-2396-4ba3-9226-f0bfd1c21f11)
• [Open in
Cursor](https://cursor.com/background-agent?bcId=bc-035967dd-2396-4ba3-9226-f0bfd1c21f11)
Learn more about [Background
Agents](https://docs.cursor.com/background-agent/web-and-mobile)
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Add a comprehensive "How to Set Up Server-Side Rendering (SSR)" guide to
provide practical, step-by-step instructions and address feedback from
PR #4703.
The previous PR #4703 aimed to add an SSR setup guide but had concerns
regarding overlap with an existing conceptual SSR guide and specific
technical implementation details (e.g., streaming SSR, Vite config).
This PR addresses those concerns by creating a distinct, practical
"how-to" guide with complete code examples, troubleshooting, and a clear
recommendation for TanStack Start, while ensuring it complements the
existing theoretical guide.
---
[Open in
Web](https://cursor.com/agents?id=bc-8555f196-638f-4bec-90a4-5eac52b5918a)
• [Open in
Cursor](https://cursor.com/background-agent?bcId=bc-8555f196-638f-4bec-90a4-5eac52b5918a)
Learn more about [Background
Agents](https://docs.cursor.com/background-agent/web-and-mobile)
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
This PR is simply adding unit test to the existing `matchByPath`
function.
However, it does highlight some weird cases / bugs:
- this test passes OK, I'm just wondering whether that's a real case
that can happen (in which case the test is good to keep) or if it's just
accidental
```ts
expect(matchByPath('/', '/a/1/b/2', { to: '/a/$id/b/$id' })).toEqual({
id: '2' })
```
- this test passes OK, I'm just a little surprised that it includes a
`/` char, because *any other* case does not
```ts
expect(matchByPath('/', '/a/', { to: '/a/$' })).toEqual({ _splat: '/',
'*': '/' })
```
- this does NOT work, it seems like a bug with the recent optional
params
```ts
expect(matchByPath('/', '/a/b', { to: '/A/{-$id}/B', caseSensitive:
false })).toEqual({})
expect(matchByPath('/', '/a/b/2', { to: '/A/{-$id}/B/{-$other}',
caseSensitive: false })).toEqual({ other: '2' })
expect(matchByPath('/', '/a/b', { to: '/A/{-$id}/B/{-$other}',
caseSensitive: false })).toEqual({})
```
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
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 (https://github.com/TanStack/router/pull/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 https://github.com/TanStack/router/pull/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.
Following up on https://github.com/TanStack/router/pull/4747
Implementation by @schiller-manuel
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
We can improve perf of this function *that gets called a lot* by not
grouping the entire string, and only removing the trailing slash.
The entire string is returned by `.replace()`, so we don't ned the group
```
> "/foo/bar/".replace(/\/$/, '')
'/foo/bar'
```
Doing so, we get ~6x performance out of it.
```
✓ @tanstack/router-core tests/other.bench.ts > comparePaths 2183ms
name hz min max mean p75 p99 p995 p999 rme samples
· oldComparePaths 1,300,774.12 0.0006 0.8563 0.0008 0.0008 0.0010 0.0010 0.0017 ±0.35% 650388
· newComparePaths 7,773,004.63 0.0000 0.2112 0.0001 0.0001 0.0002 0.0002 0.0004 ±0.14% 3886503 fastest
BENCH Summary
@tanstack/router-core newComparePaths - tests/other.bench.ts > comparePaths
5.98x faster than oldComparePaths
```
A lot of our e2e tests are querying external endpoints like
[typicode.com](https://jsonplaceholder.typicode.com) or
[example.com](https://example.com)
This is not ideal as it makes the e2e tests beholden to external factors
for example unavailability or rate limiting of these endpoints.
This PR addresses this by starting and stopping a local dummy server for
each test that needs to query external endpoints and mocks the results.
The setup and teardown have been implemented on each test package
individually so as to allow custom requirements where needed.
---------
Co-authored-by: Sean Cassiere <33615041+SeanCassiere@users.noreply.github.com>
Using integers instead of strings when possible is always better for
performance. It uses less memory, and enables faster comparisons.
This is also preparatory work for a build-time `parsePathname` as it
will result in a smaller output (though once gzipped it might not make a
difference in downloaded kB in the end).
`parsePathname` should return a `ReadonlyArray` instead of `Array`, and
`Segment` should be `readonly` too. This is because if we want to
improve perf by either caching at runtime or pre-computing routes at
build time, we need to ensure those objects can't be manipulated.
An unrelated change in this PR is also to move some inline functions to
module-scoped functions: `segmentToString` (from `resolvePath`) and
`isMatch` (from `matchByPath`). Those functions are in the hot path so
it's nice if the runtime compiler can promote them to optimized
functions.
---------
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
<!-- One very short sentence on the WHAT and WHY of the PR. E.g. "Remove
pathHash attribute because it is confirmed unused." or "Add DNS round
robin to improve load distribution." -->
Add a comprehensive how-to guide for deploying TanStack Router to
production and establish a multi-PR process for future documentation.
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Fixes#4673
I a bit simplified the `UseLinkReactProps` to make more use of typing
from React (and this simplification just fixes the bug)
Also added a test to check that the bug is no longer reproduced
Add new 'How-To' documentation section for React with a terse
installation guide to provide bite-sized, task-oriented instructions.
This new section aims to provide extremely concise, step-by-step
instructions for common tasks, making it easier for users and AI to
quickly find and follow specific procedures. Existing guides that
previously contained detailed installation steps now reference this new,
focused how-to guide to avoid content duplication and improve
discoverability.
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Add documentation for prefix-based internationalization (i18n) using
Optional Path Parameters.
This PR adds a comprehensive guide on implementing i18n patterns,
covering:
- Prefix-based i18n routing (e.g., `/{-$locale}/about`)
- Complex i18n patterns with multiple optional parameters
- Language navigation using function-style `params` for `Link`
components
- Advanced i18n with route groups
- SEO best practices (canonical URLs, hreflang)
- Type safety for locale validation
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>