Skip to content
Source
Sign inSign up
TanStack/router

docs(history): clarify blockerFn boolean contract #5414

OpenChristopher96u(GitHub profile, opens in a new tab)wants to merge 1 commit intomain fromrefs/pull/5414/headopened

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.
    1. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: history

    2. 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 nameStatusExplanationResolution
      Docstring Coverage⚠️ WarningDocstring 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 nameStatusExplanation
      Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
      Title Check✅ PassedThe 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✅ PassedThe 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✅ PassedAll 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 30970808c5e472d8b91f058f6c382cc129e1b380 and 7c2f75b4cd9268558b69715ca13854aadb7920f4.

      📒 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
      Comment `@coderabbitai help` to get the list of available commands and usage tips.
    3. View your CI Pipeline Execution ↗ for commit 7c2f75b4cd9268558b69715ca13854aadb7920f4

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

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

    4. More templates

      @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

    5. This clarification is still relevant. Could you rebase the PR and move the documentation change to docs/router/api/router/useBlockerHook.md? The ShouldBlockNavigation rename and compatibility alias still match the current blocker behaviour, I believe

Sign in to join this conversation.