Skip to content
Source
Sign inSign up
TanStack/router

docs: extend agent performance and Webpack guidance #8267

OpenLadyBluenotes(GitHub profile, opens in a new tab)wants to merge 11 commits intomain fromdocs/agent-performance-auditopened

🎯 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.
    1. Review in Change Stack →

      No actionable comments were generated in the recent review.

      Recent review info
      Run configuration
      Commits

      Reviewing files that changed from the base of the PR and between 50f0728b58a1743a6aab52e3235d5a736fe4eb8f and b84762f7247ac2d4d33403b3a650288e3a59ab60.

      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

      • TanStack/router#8794: The new guidance covers compiler instances, build phases, cache lifetimes, and memory checks.
      • TanStack/router#8792: The new guidance includes emitted-chunk and lifecycle checks related to chunk loading and readiness.
      • TanStack/router#8789: The new guidance covers hydration scheduling and script-execution checks.
      • TanStack/router#8783: The new guidance includes checks for disabled features, hydration scheduling, and navigation lifecycle behavior.
      • TanStack/router#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: Passed 4
      Check nameStatusExplanation
      Title checkPassedThe 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 CoveragePassedNo 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 checkPassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes checkPassedCheck 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.
    2. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-plugin

    3. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: history

    4. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: router-devtools-core

    5. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: start-plugin-core

    6. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: react-start-rsc

    7. 🚀 Changeset Version Preview

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

    8. View your CI Pipeline Execution ↗ for commit b84762f7247ac2d4d33403b3a650288e3a59ab60

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded13m 9sView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded1m 49sView ↗

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

    9. Bundle Size Benchmarks

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

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

    11. Merging this PR will degrade performance by 8.47%

      2 warnings, 1 note

      :warning: 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

      :warning: 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

      :information_source: 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 benchmarks1

      Warning

      Please fix the performance issues or acknowledge them on CodSpeed.

      Performance Changes

      ModeBenchmarkBASEHEADEfficiency
      ❌Memorymem client navigation-churn (solid)107.4 KB117.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)[^unexpected-base] Open in CodSpeed

      Footnotes

      1. 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. ↩

    12. skills/bundle-size-optimization/SKILL.md line 3Outdated
      @@ -1,3 +1,3 @@
      11 ---
      22 name: bundle-size-optimization
      3-description: Use when working in this repository on JS bundle size, gzip regressions, benchmark scenarios, source attribution, treeshaking, dead code elimination, or Rolldown annotations.
      3+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

    13. ⚠️ No Changeset found

      Latest commit: b84762f7247ac2d4d33403b3a650288e3a59ab60

      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

Sign in to join this conversation.