docs: extend agent performance and Webpack guidance by LadyBluenotes · Pull Request #8267 · TanStack/router

LadyBluenotes · 2026-09-06T16:56:55Z

🎯 Changes

Stacked on #8258 and targeting agents-redone.

Adds scoped performance-review guidance for evidence, coverage, finding capture, and benchmark provenance. Webpack checks cover build phases, production mode versus host environment, source maps, cache invalidation, multiple compiler instances, and emitted chunks/side effects.

Adds lifecycle checks for disabled features, router replacement, hydration scheduling, script execution, devtools, and RSC diagnostics. Keeps the full bundle measurement and attribution workflow while replacing mandatory commits/stashing and a fixed reviewer count with isolated comparisons and explicit authority.

✅ 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

Documentation
- Updated repository guidance for troubleshooting, testing, formatting, and running project tools.
- Added performance review guidance covering benchmarks, supported build tools, runtime behavior, and deployment checks.
- Expanded testing guidance for hot updates, route changes, and test discovery.
- Updated bundle-size review guidance with instructions for comparing isolated builds and checking shipped output.

coderabbitai · 2026-09-06T16:57:04Z

No actionable comments were generated in the recent review.

Recent review info

Run configuration

Source mode: Auto
Repository: TanStack/router
Branch: docs/agent-performance-audit
File: .coderabbit.yaml
Commit: b84762f
Layers: Repository YAML
Review profile: CHILL
Plan: Advanced
Run ID: 9ae868c6-a93a-41c7-822b-0a1de31af89f

Commits

Reviewing files that changed from the base of the PR and between 50f0728 and b84762f.

Files selected for processing: 2

AGENTS.md
skills/bundle-size-optimization/SKILL.md

Files skipped from review as they are similar to previous changes: 1

skills/bundle-size-optimization/SKILL.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

Walkthrough

The pull request updates repository and package guidance, revises the bundle-size optimization skill, and adds a performance-review skill with procedures for selecting checks, comparing measurements, and validating runtime and build behavior.

Changes: Review and Validation Guidance

Layer / File(s)	Summary
Contributor validation and skill references `AGENTS.md`, `e2e/AGENTS.md`, `packages/AGENTS.md`, `packages/router-plugin/AGENTS.md`	Repository and package instructions add guidance on validation, troubleshooting, test discovery, and HMR behavior. The root instructions link to the performance-review and bundle-size skills.
Performance review procedures `skills/performance-review/SKILL.md`, `skills/performance-review/references/checks.md`	The new skill defines check selection, comparable measurements, investigation, and regression validation. Its reference covers build tools, HMR, runtime lifecycles, deployment caching, browser and server measurements, and review of the procedures.
Bundle-size optimization checks `skills/bundle-size-optimization/SKILL.md`	The skill revises build coordination, benchmark comparisons, optimization review, runtime measurement, post-optimization validation, and dead-code-elimination checks.

Priority: Low

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

Change: Other

Possibly related issues

[Start] vite build keeps every environment's server-fn compiler alive until the build ends (memory stacks across client → ssr → server) #8794: The new guidance covers compiler instances, build phases, cache lifetimes, and memory checks.
router.load() resolves before an ancestor boundary's code-split errorComponent is loaded (regression in 1.170.19) #8792: The new guidance includes emitted-chunk and lifecycle checks related to chunk loading and readiness.
ssr.nonce set after the router is created no longer reaches the hydration scripts (regression in 1.171.31) #8789: The new guidance covers hydration scheduling and script-execution checks.
ssr:false: redirect thrown in a child beforeLoad during the initial load blanks the app (MatchInner throws undefined), reproducer for #7910 #8783: The new guidance includes checks for disabled features, hydration scheduling, and navigation lifecycle behavior.
router-ssr-query-core: reader.releaseLock() can deadlock WebKit's GC after hydration #8795: The new guidance covers runtime cleanup, hydration, and RSC diagnostics.

Possibly related PRs

TanStack/router#8806: The performance-review guidance includes dependency-upgrade and stream-lifecycle checks.
TanStack/router#8541: The router-plugin instructions cover generated statements and HMR accept/dispose behavior.
TanStack/router#8797: The performance-review procedures cover compiler lifetimes, cleanup, and build-tool validation.

Suggested labels: documentation

Suggested reviewers: schiller-manuel

Merge Risk: Minimal · up to b8476

No actionable merge-blocking risk is established in the documentation and guidance changes.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		The title "docs: extend agent performance and Webpack guidance" matches the main change. The PR adds performance-review guidance (new skill and references) and extends the bundle-size and AGENTS.md gu…
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title "docs: extend agent performance and Webpack guidance" matches the main change. The PR adds performance-review guidance (new skill and references) and extends the bundle-size and AGENTS.md guidance with Webpack-specific checks. The title is specific and follows the conventional-commit style. It omits the replacement of commit/stash steps and the benchmark-provenance changes, but those are secondary details.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (2 skipped: 2 unsupported.)

Finishing Touches

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

github-actions · 2026-09-06T16:58:20Z

🚀 Changeset Version Preview

No changeset entries found. Merging this PR will not cause a version bump for any packages.

nx-cloud · 2026-09-06T16:59:43Z

View your CI Pipeline Execution ↗ for commit b84762f

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

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

github-actions · 2026-09-06T17:03:05Z

Bundle Size Benchmarks

This pull request does not affect bundle size in any measured scenario.

pkg-pr-new · 2026-09-06T17:06:47Z

More templates

@tanstack/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: b84762f

codspeed · 2026-09-06T17:16:35Z

Merging this PR will degrade performance by 8.47%

2 warnings, 1 note

⚠️ 36 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

⚠️ Base and head ran on different runner types

Some benchmarks with significant performance changes were compared across different runner types, so the changes might not come from the code. Run base and head on the same runner type, or use CodSpeed Macro Runners for more stable results.

Learn more about Macro Runners

Open the report in CodSpeed to investigate

ℹ️ 3 benchmarks have no flamegraph

The flamegraph wasn't generated: most of the time was spent in runtime internals, which would leave nothing useful to analyze.

See affected benchmarks

❌ 1 regressed benchmark
✅ 193 untouched benchmarks
⏩ 3 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	`BASE`	`HEAD`	Efficiency
❌	Memory	`mem client navigation-churn (solid)`	107.4 KB	117.3 KB	-8.47%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

_{Comparing docs/agent-performance-audit (b84762f) with main (6b9fe6d)²}

3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩
No successful run was found on main (78caf5f) during the generation of this report, so 6b9fe6d was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

schiller-manuel · 2026-09-16T21:23:48Z

@@ -1,6 +1,6 @@
 ---
 name: bundle-size-optimization
-description: Use when working in this repository on JS bundle size, gzip regressions, benchmark scenarios, source attribution, treeshaking, dead code elimination, or Rolldown annotations.
+description: Use when working in this repository on JS bundle size, gzip regressions, benchmark scenarios, source attribution, treeshaking, dead code elimination, or bundler annotations, including Webpack.


mention both rolldown and webpack or none of them

# Conflicts: # AGENTS.md # benchmarks/AGENTS.md

changeset-bot · 2026-10-24T21:48:28Z

⚠️ No Changeset found

Latest commit: b84762f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

schiller-manuel and others added 3 commits September 6, 2026 00:26

agents

34650b7

update

07d86bc

docs: extend agent performance review guidance

2b25012

github-actions Bot added package: router-plugin package: history package: router-devtools-core package: start-plugin-core package: react-start-rsc labels Sep 6, 2026

LadyBluenotes marked this pull request as ready for review September 6, 2026 16:58

LadyBluenotes requested a review from a team as a code owner September 6, 2026 16:58

docs: consolidate performance guidance in shared guide

3368c3d

LadyBluenotes added 3 commits September 6, 2026 16:46

docs: capture Router and Start audit lessons

3ec5cdf

docs: separate performance checks from personal workflows

b8124f5

docs: move performance checks into the review skill

5a6bdb2

LadyBluenotes removed the request for review from a team September 7, 2026 22:48

ci: refresh performance comparison with clean base results

1ed7793

schiller-manuel force-pushed the agents-redone branch from 07d86bc to ce1aab4 Compare September 15, 2026 20:21

Base automatically changed from agents-redone to main September 15, 2026 20:36

schiller-manuel reviewed Sep 16, 2026

View reviewed changes

schiller-manuel requested a review from Sheraff September 16, 2026 21:25

LadyBluenotes added 3 commits September 24, 2026 18:03

Merge branch 'main' into docs/agent-performance-audit

fc78918

docs(skills): drop bundler-specific mention from skill description

50f0728

Merge branch 'main' into docs/agent-performance-audit

b84762f

# Conflicts: # AGENTS.md # benchmarks/AGENTS.md

LadyBluenotes mentioned this pull request Oct 24, 2026

Tracking: open Router and Start PRs by problem area #8810

Open

23 tasks

coderabbitai Bot mentioned this pull request Oct 24, 2026

ci: upgrade Nx and migrate worker configuration #8807

Merged

4 of 5 tasks

Navigation Menu

Repository navigation

docs: extend agent performance and Webpack guidance - #8267

docs: extend agent performance and Webpack guidance#8267
LadyBluenotes wants to merge 11 commits into
mainfrom
docs/agent-performance-audit

LadyBluenotes commented Sep 6, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Sep 6, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 6, 2026 •

edited

Loading

Uh oh!

nx-cloud Bot commented Sep 6, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 6, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Sep 6, 2026 •

edited

Loading

Uh oh!

codspeed Bot commented Sep 6, 2026 •

edited

Loading

Uh oh!

schiller-manuel Sep 16, 2026

Uh oh!

changeset-bot Bot commented Oct 24, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

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

Uh oh!

🎯 Changes

✅ Checklist

🚀 Release Impact

Summary by CodeRabbit

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

🚀 Changeset Version Preview

Uh oh!

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

Uh oh!

Uh oh!

github-actions Bot commented Sep 6, 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 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Merging this PR will degrade performance by 8.47%

Performance Changes

Footnotes

Uh oh!

schiller-manuel Sep 16, 2026

Choose a reason for hiding this comment

Uh oh!

changeset-bot Bot commented Oct 24, 2026

⚠️ No Changeset found

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

LadyBluenotes commented Sep 6, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Sep 6, 2026 •

edited

Loading

github-actions Bot commented Sep 6, 2026 •

edited

Loading

nx-cloud Bot commented Sep 6, 2026 •

edited

Loading

github-actions Bot commented Sep 6, 2026 •

edited

Loading

pkg-pr-new Bot commented Sep 6, 2026 •

edited

Loading

codspeed Bot commented Sep 6, 2026 •

edited

Loading