perf(react-router): avoid unnecessary composed handlers

[Sheraff]

Summary

Avoid allocating six event-handler arrays and wrapper closures for links that do not provide user event handlers.

The two-argument composeHandlers returns the internal handler directly when the user handler is absent. When a user handler is present, it preserves the existing ordering and defaultPrevented semantics. The wrapper uses a short-circuit expression so the emitted handler remains compact; the suggested nested if form minifies to the same output as the original block form.

Performance

Focused client navigation benchmark using the React links scenario (200 links, repeated navigation loop; same local environment, one run per version):

Version	Throughput	Mean time
Before	195.60 Hz	5.1126 ms
After	196.62 Hz	5.0859 ms
Change	+0.52%	-0.52%

The runtime result is effectively neutral within benchmark noise. The important workload improvement is avoiding per-link allocations during render.

Bundle-size benchmark for react-router.minimal:

Metric	Before	After	Change
gzip	85,841 B	85,843 B	+2 B
initial gzip	85,703 B	85,706 B	+3 B
raw	268,585 B	268,575 B	-10 B
brotli	74,705 B	74,742 B	+37 B

The compact expression improves the committed implementation by 3 gzip bytes (85,846 B -> 85,843 B), reducing the optimization's gzip impact to +2 bytes over the original array composer.

Tests

• Added focused composeHandlers event-semantics tests, including already-prevented events.
• Added a retained allocation/identity benchmark for the old and new composers.
• @tanstack/react-router:test:unit — 1,097 passed, 1 skipped.
• @tanstack/react-router:test:types — passed.
• @tanstack/react-router:test:eslint — passed.
• React client links benchmark — passed.

Summary by CodeRabbit

• Performance

  • Improved link efficiency by avoiding unnecessary event-handler wrappers when no custom handlers are provided.
  • Reduced allocations during link rendering and interaction, supporting smoother navigation.

• Bug Fixes

  • Preserved expected event behavior when default actions have already been prevented.
  • Ensured internal link handling runs only when appropriate, including when custom handlers prevent the default action.
  • Maintained consistent behavior for links with and without custom event handlers.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-07T10:24:16.146581Z	f4131e2	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 3e584cb

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

---

☁️ Nx Cloud last updated this comment at 2026-09-07 11:19:41 UTC

[github-actions]

🚀 Changeset Version Preview

1 package(s) bumped directly, 4 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/react-router	1.170.33 → 1.170.34	Changeset
@tanstack/react-start	1.168.50 → 1.168.51	Dependent
@tanstack/react-start-client	1.168.31 → 1.168.32	Dependent
@tanstack/react-start-rsc	0.1.49 → 0.1.50	Dependent
@tanstack/react-start-server	1.167.38 → 1.167.39	Dependent

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 94db2598-e777-4bf0-8645-372c5c15a1b6

📥 Commits

Reviewing files that changed from the base of the PR and between f4131e2 and 3e584cb.

📒 Files selected for processing (1)

• packages/react-router/src/link.tsx

Included review availability: Your plan provides up to 10 included reviews per hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

React Router now composes link event handlers with two arguments. It returns the internal handler directly when no user handler exists and preserves defaultPrevented short-circuiting. Tests, benchmarks, and a patch changeset cover the update.

Changes

Event handler composition

Layer / File(s)	Summary
Two-handler composition and link integration packages/react-router/src/link.tsx, .changeset/fast-compose-handlers.md	composeHandlers now accepts separate handlers, returns the internal handler when no user handler exists, and is used for six link events. A patch changeset records the release.
Composition behavior validation and benchmarks packages/react-router/tests/link.test.tsx, packages/react-router/tests/composeHandlers.bench.ts	Tests cover handler ordering and defaultPrevented behavior. Benchmarks compare direct handler reuse and wrapper allocation.

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

Merge Risk: ⚪ Minimal · up to fece6

Link event handlers now avoid unnecessary allocations when no user handler is supplied while preserving cancellation and invocation behavior. The changed behavior is covered by focused tests and introduces no active merge-blocking risk.

Suggested reviewers: schiller-manuel

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 2 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	⚠️ Warning	The description explains the implementation, motivation, performance data, tests, and validation results. It does not follow the required template because it omits the Changes, Checklist, and Release …	Add the required template sections. Include the Changes section, complete each Checklist item, and state that the published code change has a generated changeset under Release Impact.

✅ Passed checks (3 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly describes the primary change: improving React Router performance by avoiding unnecessary composed handlers.

Full details: Description check

Explanation

The description explains the implementation, motivation, performance data, tests, and validation results. It does not follow the required template because it omits the Changes, Checklist, and Release Impact sections, including the required checklist items and changeset declaration.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fast-compose-handlers

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Bundle Size Benchmarks

• Commit: 1dcad7efa9a7
• Measured at: 2026-09-07T11:06:51.002Z
• Baseline source: history:a58e01c604e2
• 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	83.8 KiB +2 B	83.7 KiB +3 B	262.3 KiB -10 B	73.0 KiB +37 B	▂▂▂▁▆▆▆▆▇███
react-router.full	87.3 KiB +3 B	87.2 KiB +3 B	274.0 KiB -10 B	76.1 KiB +128 B	▁▁▁▁█▅▅▅▆▆▆▇
react-start.minimal	96.7 KiB +2 B	96.6 KiB +2 B	304.5 KiB -10 B	83.8 KiB +3 B	▂▂▂▁█▆▆▆▇███
react-start.query-integration	104.1 KiB -4 B	103.9 KiB -1 B	331.0 KiB -10 B	90.2 KiB -36 B	▁▁▁▃█▄▄▄▆▇▇▇
react-start.deferred-hydration	97.5 KiB +2 B	96.6 KiB +3 B	305.9 KiB -10 B	84.5 KiB -12 B	▁▁▁▂█▅▅▅▇███
react-start.full	99.9 KiB 0 B	99.8 KiB 0 B	314.2 KiB -10 B	86.5 KiB +70 B	▁▁▁▂█▆▆▆▇██
react-start.rsbuild.minimal	100.0 KiB -6 B	99.9 KiB -6 B	314.8 KiB -10 B	86.3 KiB +81 B	▁▁▁▃█▆▆▆▇▇▇▇
react-start.rsbuild.minimal-iife	100.4 KiB -6 B	100.3 KiB -6 B	315.8 KiB -10 B	86.6 KiB +37 B	▁▁▁▃█▆▆▆▇██▇
react-start.rsbuild.full	103.4 KiB -5 B	103.2 KiB -5 B	324.9 KiB -10 B	89.1 KiB +45 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]

More templates

• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-rsbuild
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-example-rscs
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query
• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc
• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc

@tanstack/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: fece6b6

[codspeed]

Merging this PR will not alter performance

✅ 180 untouched benchmarks

---

_{Comparing codex/fast-compose-handlers (fece6b6) with main (a58e01c)}