perf(history): avoid generating unused location keys by LadyBluenotes · Pull Request #8349 · TanStack/router

LadyBluenotes · 2026-09-11T02:20:01Z

🎯 Changes

Generate a fallback history key in parseHref only when no state is supplied. Parsing a location with existing state no longer creates and discards a random key.

Performance

Local Node.js 24.12.0 microbenchmark comparing 6494e75362 with 9eeb94f921. Nine alternating baseline/candidate rounds per case, with 100,000 warmup calls and 2,000,000 timed calls per sample. The URL is /items/123?tab=details#top; times below are medians.

Case	Before	After	Change
`parseHref` with existing state	375.41 ms	115.24 ms	About 69% less elapsed time
`parseHref` without state	382.24 ms	382.98 ms	About +0.2%; within observed run variation
Minimal React Router bundle, gzip	85,993 bytes	85,996 bytes	+3 bytes

Existing-state parsing removes one discarded key-generation operation per call. These are isolated runtime results, not an end-to-end navigation speedup or a retained-heap measurement.

✅ Checklist

I have followed the steps in the Contributing guide.
I have tested code changes locally with the relevant test commands, or tests do not apply to this pull request.
I fully understand the code in this pull request, including any code generated with AI assistance.

🚀 Release Impact

This change affects published code, and I have generated a changeset.
This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

Bug Fixes
- Existing location state is now preserved without generating an unnecessary history key.
- Locations created without state continue to receive independent initial state, including a unique key and index.
Tests
- Added coverage for preserving supplied state and isolating automatically generated location state.

coderabbitai · 2026-09-11T02:20:23Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: e931f2e4-acc9-4c7d-bb1f-4312cfb65d21

📥 Commits

Reviewing files that changed from the base of the PR and between 3302f6b and a2f58a3.

📒 Files selected for processing (1)

packages/history/src/index.ts

📝 Walkthrough

Walkthrough

parseHref now preserves supplied state and creates independent keyed state objects when state is absent. Tests cover both behaviors. A patch changeset documents the fix for @tanstack/history.

Changes

History state preservation

Layer / File(s)	Summary
Conditional history state creation `packages/history/src/index.ts`	`assignKeyAndIndex` and `parseHref` create default keyed state only when the input state is absent.
State preservation tests and release metadata `packages/history/tests/parseHref.test.ts`, `.changeset/lazy-locations-listen.md`	Tests verify exact preservation of supplied frozen state and independence of generated default states. The changeset records a patch release for `@tanstack/history`.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Refactor

Merge Risk: ⚪ Minimal · up to 3302f

The supplied change preserves provided history state and adds coverage for both supplied and generated state behavior, with no remaining merge-blocking risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ 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%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the history performance change: it avoids generating unused location keys.
Description check	✅ Passed	The description explains the change and motivation, reports benchmark results, completes the checklist, and includes the required changeset for published code.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Fix all pre-merge checks with AI

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch perf/history-lazy-location-key

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

nx-cloud · 2026-09-11T02:20:28Z

View your CI Pipeline Execution ↗ for commit 9eeb94f

Command	Status	Duration	Result
`nx affected --targets=test:eslint,test:unit,tes...`	⏳ In Progress	...	View ↗
`nx run-many --target=build --exclude=examples/*...`	✅ Succeeded	1m 25s	View ↗

☁️ Nx Cloud last updated this comment at 2026-09-12 20:21:36 UTC

github-actions · 2026-09-11T02:21:27Z

🚀 Changeset Version Preview

3 package(s) bumped directly, 21 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
`@tanstack/history`	1.162.3 → 1.162.4	Changeset
`@tanstack/router-core`	1.171.29 → 1.171.30	Changeset
`@tanstack/start-server-core`	1.169.34 → 1.169.35	Changeset
`@tanstack/react-router`	1.170.35 → 1.170.36	Dependent
`@tanstack/react-start`	1.168.52 → 1.168.53	Dependent
`@tanstack/react-start-client`	1.168.33 → 1.168.34	Dependent
`@tanstack/react-start-rsc`	0.1.51 → 0.1.52	Dependent
`@tanstack/react-start-server`	1.167.40 → 1.167.41	Dependent
`@tanstack/router-cli`	1.167.35 → 1.167.36	Dependent
`@tanstack/router-generator`	1.167.35 → 1.167.36	Dependent
`@tanstack/router-plugin`	1.168.37 → 1.168.38	Dependent
`@tanstack/router-vite-plugin`	1.167.37 → 1.167.38	Dependent
`@tanstack/solid-router`	1.170.33 → 1.170.34	Dependent
`@tanstack/solid-start`	1.168.50 → 1.168.51	Dependent
`@tanstack/solid-start-client`	1.168.32 → 1.168.33	Dependent
`@tanstack/solid-start-server`	1.167.39 → 1.167.40	Dependent
`@tanstack/start-client-core`	1.170.29 → 1.170.30	Dependent
`@tanstack/start-plugin-core`	1.171.42 → 1.171.43	Dependent
`@tanstack/start-static-server-functions`	1.167.34 → 1.167.35	Dependent
`@tanstack/start-storage-context`	1.167.31 → 1.167.32	Dependent
`@tanstack/vue-router`	1.170.32 → 1.170.33	Dependent
`@tanstack/vue-start`	1.168.49 → 1.168.50	Dependent
`@tanstack/vue-start-client`	1.167.35 → 1.167.36	Dependent
`@tanstack/vue-start-server`	1.167.39 → 1.167.40	Dependent

github-actions · 2026-09-11T02:23:11Z

Bundle Size Benchmarks

Commit: 0898b4f379c6
Measured at: 2026-09-12T20:21:14.144Z
Baseline source: history:8fff7fa1f2e6
Dashboard: bundle-size history

The following scenarios have bundle-size changes compared with the baseline:

Scenario	Current (gzip)	Initial (gzip)	Raw	Brotli	Trend
`react-router.minimal`	84.0 KiB -1 B	83.8 KiB -4 B	262.3 KiB +5 B	73.2 KiB -12 B	█████▁▁▁▁▁▁
`react-router.full`	87.5 KiB -9 B	87.3 KiB -6 B	274.0 KiB +5 B	76.2 KiB -62 B	█████▂▂▂▂▂▁
`solid-router.minimal`	33.4 KiB -6 B	33.3 KiB -2 B	96.8 KiB +5 B	30.3 KiB -39 B	▁█████████▄
`solid-router.full`	38.3 KiB -6 B	38.2 KiB -4 B	111.4 KiB +5 B	34.4 KiB -51 B	▂█████████▁
`vue-router.minimal`	49.6 KiB -7 B	49.5 KiB -7 B	138.3 KiB +5 B	44.9 KiB -2 B	█████▁▁▁▁▁▁
`vue-router.full`	55.2 KiB -4 B	55.1 KiB -6 B	156.5 KiB +5 B	49.8 KiB -6 B	█████▁▁▁▁▁▁
`react-start.minimal`	96.9 KiB -9 B	96.7 KiB -7 B	304.6 KiB +5 B	84.0 KiB -65 B	█████▁▁▁▁▁▁
`react-start.query-integration`	104.2 KiB -8 B	104.1 KiB -4 B	331.1 KiB +5 B	90.4 KiB +16 B	█████▁▁▁▁▁▁
`react-start.deferred-hydration`	97.6 KiB -2 B	96.8 KiB -3 B	305.9 KiB +5 B	84.7 KiB -1 B	█████▁▁▁▁▁▁
`react-start.full`	100.0 KiB -3 B	99.9 KiB -5 B	314.3 KiB +5 B	86.7 KiB +5 B	█████▁▁▁▁▁▁
`react-start.rsbuild.minimal`	100.1 KiB -5 B	100.0 KiB -5 B	314.9 KiB +2 B	86.5 KiB +55 B	█████▁▁▁▁▁▁
`react-start.rsbuild.minimal-iife`	100.5 KiB -5 B	100.4 KiB -5 B	315.8 KiB +2 B	86.8 KiB -89 B	█████▁▁▁▁▁▁
`react-start.rsbuild.full`	103.4 KiB -5 B	103.2 KiB -5 B	324.9 KiB +2 B	89.2 KiB -39 B	█████▁▁▁▁▁▁
`solid-start.minimal`	46.3 KiB -4 B	46.2 KiB -2 B	137.9 KiB +5 B	41.2 KiB -19 B	█▄▄▄▄▄▄▄▄▄▁
`solid-start.deferred-hydration`	49.4 KiB +4 B	46.3 KiB 0 B	145.3 KiB +5 B	44.0 KiB -47 B	▁▅▅▅▅▅▅▅▅▅█
`solid-start.full`	51.4 KiB -4 B	51.3 KiB -3 B	153.3 KiB +5 B	45.5 KiB -31 B	█▆▆▆▆▆▆▆▆▆▁
`vue-start.minimal`	65.7 KiB -2 B	65.6 KiB -4 B	189.2 KiB +5 B	58.5 KiB -78 B	█████▁▁▁▁▁▁
`vue-start.full`	69.6 KiB -3 B	69.4 KiB -4 B	201.5 KiB +5 B	61.8 KiB -39 B	█████▁▁▁▁▁▁

Current gzip tracks all emitted client JS chunks. Initial gzip tracks only the entry/import graph. Trend sparkline is historical current gzip ending with this PR measurement; lower is better.

pkg-pr-new · 2026-09-11T02:25:31Z

More templates

@tanstack/arktype-adapter

npm i https://pkg.pr.new/@tanstack/arktype-adapter@8349

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@8349

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@8349

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

npm i https://pkg.pr.new/@tanstack/react-start@8349

@tanstack/react-start-client

npm i https://pkg.pr.new/@tanstack/react-start-client@8349

@tanstack/react-start-rsc

npm i https://pkg.pr.new/@tanstack/react-start-rsc@8349

@tanstack/react-start-server

npm i https://pkg.pr.new/@tanstack/react-start-server@8349

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

npm i https://pkg.pr.new/@tanstack/solid-start@8349

@tanstack/solid-start-client

npm i https://pkg.pr.new/@tanstack/solid-start-client@8349

@tanstack/solid-start-server

npm i https://pkg.pr.new/@tanstack/solid-start-server@8349

@tanstack/start-client-core

npm i https://pkg.pr.new/@tanstack/start-client-core@8349

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/@tanstack/start-fn-stubs@8349

@tanstack/start-plugin-core

npm i https://pkg.pr.new/@tanstack/start-plugin-core@8349

@tanstack/start-server-core

npm i https://pkg.pr.new/@tanstack/start-server-core@8349

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

npm i https://pkg.pr.new/@tanstack/start-storage-context@8349

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@8349

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@8349

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

npm i https://pkg.pr.new/@tanstack/vue-start@8349

@tanstack/vue-start-client

npm i https://pkg.pr.new/@tanstack/vue-start-client@8349

@tanstack/vue-start-server

npm i https://pkg.pr.new/@tanstack/vue-start-server@8349

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@8349

commit: 9eeb94f

nx-cloud

Important

At least one additional CI pipeline execution has run since the conclusion below was written and it may no longer be applicable.

Nx Cloud has identified a possible root cause for your failed CI:

We determined these E2E failures are environment-related and not caused by this PR. The parseHref change is a functionally identical performance optimization, and neither failing project is in the set of projects touched by the diff. The React test shows explicit ECONNRESET network errors from the test server, and the Solid test is a router-idle timeout — both pointing to infrastructure instability rather than a logic regression.

No code changes were suggested for this issue.

Trigger a rerun:

View detailed reasoning on Nx Cloud ↗

_{🎓 Learn more about Self-Healing CI on nx.dev}

codspeed-hq · 2026-09-11T02:38:31Z

Merging this PR will not alter performance

✅ 180 untouched benchmarks

_{Comparing perf/history-lazy-location-key (a2f58a3) with main (8fff7fa)}

Sheraff · 2026-09-12T20:06:51Z

This looks very mergeable.

while you're at it, can we also do this? falsy values are spread-able in JS

function assignKeyAndIndex(index: number, state: HistoryState | undefined) {
-  if (!state) {
-    state = {}
-  }
  const key = createRandomKey()
  return {
    ...state,
    key, // TODO: Remove in v2 - use __TSR_key instead
    __TSR_key: key,
    [stateIndexKey]: index,
  } as ParsedHistoryState
}

LadyBluenotes · 2026-09-12T20:17:53Z

This looks very mergeable.

while you're at it, can we also do this? falsy values are spread-able in JS

function assignKeyAndIndex(index: number, state: HistoryState | undefined) {
-  if (!state) {
-    state = {}
-  }
  const key = createRandomKey()
  return {
    ...state,
    key, // TODO: Remove in v2 - use __TSR_key instead
    __TSR_key: key,
    [stateIndexKey]: index,
  } as ParsedHistoryState
}

done

…dIndex Spreading undefined is a no-op, so the guard was dead weight.

github-actions Bot added the package: history label Sep 11, 2026

LadyBluenotes requested a review from schiller-manuel September 11, 2026 02:30

nx-cloud Bot reviewed Sep 11, 2026

View reviewed changes

LadyBluenotes and others added 2 commits September 12, 2026 13:17

perf(history): avoid generating unused location keys

57e69e9

refactor(history): drop redundant empty-state fallback in assignKeyAn…

a2f58a3

…dIndex Spreading undefined is a no-op, so the guard was dead weight.

LadyBluenotes force-pushed the perf/history-lazy-location-key branch from 3302f6b to a2f58a3 Compare September 12, 2026 20:17

Sheraff approved these changes Sep 12, 2026

View reviewed changes

LadyBluenotes merged commit ae68535 into main Sep 12, 2026
10 of 11 checks passed

LadyBluenotes deleted the perf/history-lazy-location-key branch September 12, 2026 20:19

github-actions Bot mentioned this pull request Sep 12, 2026

ci: Version Packages #8355

Open

Navigation Menu

Uh oh!

Uh oh!

perf(history): avoid generating unused location keys - #8349

perf(history): avoid generating unused location keys#8349
LadyBluenotes merged 2 commits into
mainfrom
perf/history-lazy-location-key

LadyBluenotes commented Sep 11, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Sep 11, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

nx-cloud Bot commented Sep 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 11, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Sep 11, 2026

Uh oh!

nx-cloud Bot left a comment •

edited

Loading

Uh oh!

codspeed-hq Bot commented Sep 11, 2026 •

edited

Loading

Uh oh!

Sheraff commented Sep 12, 2026

Uh oh!

LadyBluenotes commented Sep 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

LadyBluenotes commented Sep 11, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎯 Changes

Performance

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

nx-cloud Bot commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Changeset Version Preview

🟩 Patch bumps

Uh oh!

github-actions Bot commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Size Benchmarks

Uh oh!

pkg-pr-new Bot commented Sep 11, 2026

Uh oh!

nx-cloud Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Nx Cloud has identified a possible root cause for your failed CI:

Uh oh!

codspeed-hq Bot commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Uh oh!

Sheraff commented Sep 12, 2026

Uh oh!

LadyBluenotes commented Sep 12, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

LadyBluenotes commented Sep 11, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Sep 11, 2026 •

edited

Loading

nx-cloud Bot commented Sep 11, 2026 •

edited

Loading

github-actions Bot commented Sep 11, 2026 •

edited

Loading

github-actions Bot commented Sep 11, 2026 •

edited

Loading

nx-cloud Bot left a comment •

edited

Loading

codspeed-hq Bot commented Sep 11, 2026 •

edited

Loading