docs(history): clarify blockerFn boolean contract

[Christopher96u]

Fixes #3876

Summary by CodeRabbit

• Documentation
  • Clarified blocker semantics: returning true blocks navigation; false allows it, improving understanding for React usage.
• Refactor
  • Introduced a clearer public type for navigation blocking and deprecated the previous allow-based alias. This is non-breaking and preserves existing behavior.
• Chores
  • Added inline comments to clarify that a truthy blocker response prevents navigation in both history creation paths.

[coderabbitai]

Walkthrough

Clarifies navigation blocker semantics: documentation now states that returning true blocks navigation and false allows it. In code, introduces ShouldBlockNavigation type, deprecates ShouldAllowNavigation as an alias, and updates BlockerFn to return boolean|Promise representing “should block” without changing runtime behavior.

Changes

Cohort / File(s)	Summary of modifications
Docs: React Router useBlockerHook docs/router/framework/react/api/router/useBlockerHook.md	Updated wording to state that returning true blocks navigation and false allows it, aligning docs with actual behavior.
History types and comments packages/history/src/index.ts	Added ShouldBlockNavigation type; deprecated ShouldAllowNavigation as alias; updated BlockerFn return type to use block semantics; added inline comments clarifying truthy means “block” across history creation paths.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I twitch my ears at types that mock,
Now truth is clear: true means block.
Old names hop off, new names hop in,
Docs align—no spin, just win.
Onward I bound through changelog dew,
Booleans sorted, carrots too. 🥕🐇

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title clearly indicates that the documentation and associated code in the history module are being updated to clarify the boolean contract of the blockerFn API, matching the primary change in the PR.
Linked Issues Check	✅ Passed	The PR directly addresses issue #3876 by clarifying the blockerFn boolean behavior in documentation and renaming the type to ShouldBlockNavigation to align with its actual semantics, satisfying the issue’s proposed resolutions.
Out of Scope Changes Check	✅ Passed	All modifications in the PR are focused on updating documentation and types related to the blockerFn boolean contract in the history package, with no unrelated or extraneous changes introduced.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 3097080 and 7c2f75b.

📒 Files selected for processing (2)

• docs/router/framework/react/api/router/useBlockerHook.md (1 hunks)
• packages/history/src/index.ts (4 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

docs/**/*.{md,mdx}

📄 CodeRabbit inference engine (AGENTS.md)

Use internal docs links relative to the docs/ folder (e.g., ./guide/data-loading)

Files:

• docs/router/framework/react/api/router/useBlockerHook.md

docs/{router,start}/**

📄 CodeRabbit inference engine (AGENTS.md)

Place router docs under docs/router/ and start framework docs under docs/start/

Files:

• docs/router/framework/react/api/router/useBlockerHook.md

**/*.{ts,tsx}

📄 CodeRabbit inference engine (AGENTS.md)

Use TypeScript in strict mode with extensive type safety across the codebase

Files:

• packages/history/src/index.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Preview
• GitHub Check: Test

🔇 Additional comments (5)

packages/history/src/index.ts (4)

76-78: LGTM!

The BlockerFn return type is correctly updated to use ShouldBlockNavigation, maintaining consistency with the type rename.

---

157-157: LGTM!

The clarifying comment accurately documents the blocking semantics and improves code maintainability.

---

446-446: LGTM!

The clarifying comment is consistent with the one at line 157 and accurately documents the blocking semantics for the browser history code path.

---

61-66: Excellent type rename with backward compatibility!

No references to ShouldAllowNavigation outside its alias; the deprecation alias ensures backward compatibility.

docs/router/framework/react/api/router/useBlockerHook.md (1)

60-60: LGTM!

The documentation update clearly states the blocking semantics, eliminating the confusion reported in issue #3876. The explicit parenthetical clarification (true blocks, false allows) leaves no room for misinterpretation.

---

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 and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 7c2f75b

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

---

☁️ Nx Cloud last updated this comment at 2025-10-09 06:12:57 UTC

[pkg-pr-new]

More templates

• tanstack-router-solid-example-basic
• 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-streaming-file-based
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-solid-start-example-bare
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-static
• 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-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• 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/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@5414

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@5414

@tanstack/eslint-plugin-router

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

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@5414

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@5414

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@5414

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@5414

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@5414

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@5414

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@5414

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@5414

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@5414

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@5414

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@5414

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@5414

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@5414

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@5414

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@5414

commit: 7c2f75b