Make useBlocker exception on unknown routes optional

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

@@ -29,8 +29,8 @@ interface ShouldBlockFnLocation<...> {
 }
 
 type ShouldBlockFnArgs = {
-  current: ShouldBlockFnLocation
-  next: ShouldBlockFnLocation
+  current: ShouldBlockFnLocation | undefined
+  next: ShouldBlockFnLocation | undefined
   action: HistoryAction
 }
 ```
@@ -53,6 +53,12 @@ type ShouldBlockFnArgs = {
 - Type: `boolean`
 - Specify if the resolver returned by the hook should be used or whether your `shouldBlockFn` function itself resolves the blocking
 
+### `options.throwOnUnknownRoute` option
+
+- Optional - defaults to `true`
+- Type: `boolean`
+- Specify if the hook should throw an exception when either the current or next locations is unkown
+
 ### `options.blockerFn` option (⚠️ deprecated)
 
 - Optional
@@ -120,7 +126,7 @@ function MyComponent() {
       {/* ... */}
       {status === 'blocked' && (
         <div>
-          <p>You are navigating to {next.pathname}</p>
+          <p>You are navigating to {next?.pathname ?? 'Unknown Path'}</p>
           <p>Are you sure you want to leave?</p>
           <button onClick={proceed}>Yes</button>
           <button onClick={reset}>No</button>
@@ -138,7 +144,7 @@ import { useBlocker } from '@tanstack/react-router'
 function MyComponent() {
   const { proceed, reset, status } = useBlocker({
     shouldBlockFn: ({ next }) => {
-      return !next.pathname.includes('step/')
+      return next && !next.pathname.includes('step/')
     },
     withResolver: true,
   })
@@ -170,7 +176,7 @@ function MyComponent() {
 
   useBlocker({
     shouldBlockFn: ({ next }) => {
-      if (next.pathname.includes('step/')) {
+      if (next?.pathname.includes('step/')) {
         return false
       }
 
@@ -195,10 +201,10 @@ function MyComponent() {
   const { proceed, reset, status } = useBlocker({
     shouldBlockFn: ({ current, next }) => {
       if (
-        current.routeId === '/editor-1' &&
-        next.fullPath === '/foo/$id' &&
-        next.params.id === '123' &&
-        next.search.hello === 'world'
+        current?.routeId === '/editor-1' &&
+        next?.fullPath === '/foo/$id' &&
+        next?.params.id === '123' &&
+        next?.search.hello === 'world'
       ) {
         return true
       }

packages/react-router/src/useBlocker.tsx

@@ -41,8 +41,8 @@ type MakeShouldBlockFnLocationUnion<
 type BlockerResolver<TRouter extends AnyRouter = RegisteredRouter> =
   | {
       status: 'blocked'
-      current: MakeShouldBlockFnLocationUnion<TRouter>
-      next: MakeShouldBlockFnLocationUnion<TRouter>
+      current: MakeShouldBlockFnLocationUnion<TRouter> | undefined
+      next: MakeShouldBlockFnLocationUnion<TRouter> | undefined
       action: HistoryAction
       proceed: () => void
       reset: () => void
@@ -57,8 +57,8 @@ type BlockerResolver<TRouter extends AnyRouter = RegisteredRouter> =
     }
 
 type ShouldBlockFnArgs<TRouter extends AnyRouter = RegisteredRouter> = {
-  current: MakeShouldBlockFnLocationUnion<TRouter>
-  next: MakeShouldBlockFnLocationUnion<TRouter>
+  current: MakeShouldBlockFnLocationUnion<TRouter> | undefined
+  next: MakeShouldBlockFnLocationUnion<TRouter> | undefined
   action: HistoryAction
 }
 
@@ -73,6 +73,7 @@ export type UseBlockerOpts<
   enableBeforeUnload?: boolean | (() => boolean)
   disabled?: boolean
   withResolver?: TWithResolver
+  throwOnUnknownRoute?: boolean
 }
 
 type LegacyBlockerFn = () => Promise<any> | any
@@ -157,6 +158,7 @@ export function useBlocker(
     enableBeforeUnload = true,
     disabled = false,
     withResolver = false,
+    throwOnUnknownRoute = true,
   } = _resolveBlockerOpts(opts, condition)
 
   const router = useRouter()
@@ -175,14 +177,14 @@ export function useBlocker(
     const blockerFnComposed = async (blockerFnArgs: BlockerFnArgs) => {
       function getLocation(
         location: HistoryLocation,
-      ): AnyShouldBlockFnLocation {
+      ): AnyShouldBlockFnLocation | undefined {
         const parsedLocation = router.parseLocation(location)
         const matchedRoutes = router.getMatchedRoutes(
           parsedLocation.pathname,
           undefined,
         )
         if (matchedRoutes.foundRoute === undefined) {
-          throw new Error(`No route found for location ${location.href}`)
+          return undefined
         }
         return {
           routeId: matchedRoutes.foundRoute.id,
@@ -194,7 +196,17 @@ export function useBlocker(
       }
 
       const current = getLocation(blockerFnArgs.currentLocation)
+      if (!current && throwOnUnknownRoute) {
+        throw new Error(
+          `No route found for location ${blockerFnArgs.currentLocation.href}`,
+        )
+      }
       const next = getLocation(blockerFnArgs.nextLocation)
+      if (!next && throwOnUnknownRoute) {
+        throw new Error(
+          `No route found for location ${blockerFnArgs.nextLocation.href}`,
+        )
+      }
 
       const shouldBlock = await shouldBlockFn({
         action: blockerFnArgs.action,
@@ -243,6 +255,7 @@ export function useBlocker(
     withResolver,
     history,
     router,
+    throwOnUnknownRoute
   ])
 
   return resolver

packages/react-router/tests/useBlocker.test-d.tsx

@@ -109,6 +109,7 @@ test('shouldBlockFn has corrent action', () => {
     .toHaveProperty('shouldBlockFn')
     .parameter(0)
     .toHaveProperty('current')
+    .exclude(undefined)
     .toHaveProperty('routeId')
     .toEqualTypeOf<'__root__' | '/' | '/invoices' | '/invoices/'>()
 
@@ -117,6 +118,7 @@ test('shouldBlockFn has corrent action', () => {
     .toHaveProperty('shouldBlockFn')
     .parameter(0)
     .toHaveProperty('next')
+    .exclude(undefined)
     .toHaveProperty('routeId')
     .toEqualTypeOf<'__root__' | '/' | '/invoices' | '/invoices/'>()
 })

packages/react-router/tests/useBlocker.test.tsx

@@ -1,10 +1,17 @@
 import React from 'react'
 import '@testing-library/jest-dom/vitest'
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
-import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import {
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+} from '@testing-library/react'
 
 import { z } from 'zod'
 import {
+  Link, 
+  Outlet,
   RouterProvider,
   createBrowserHistory,
   createRootRoute,
@@ -360,7 +367,7 @@ describe('useBlocker', () => {
 
       useBlocker<Router>({
         shouldBlockFn: ({ next }) => {
-          if (next.fullPath === '/posts') {
+          if (next?.fullPath === '/posts') {
             return true
           }
           return false
@@ -440,4 +447,52 @@ describe('useBlocker', () => {
 
     expect(window.location.pathname).toBe('/invoices')
   })
+
+  test('does not throw when navigating to an unknown route and throwOnUnknownRoute is false', async () => {
+    const rootRoute = createRootRoute({
+      component:() => <Outlet />,
+      notFoundComponent: () => <h1 data-testid="not-found">Not Found</h1>,
+    })
+
+    const IndexComponent = () => {
+      useBlocker({ 
+        shouldBlockFn: () => false, 
+        throwOnUnknownRoute: false 
+      })
+
+      return (
+        <>
+          <h1>Index</h1>
+          <Link data-testid='unknown-link' to='/unknown'>
+            Unknown
+          </Link>
+        </>
+      )
+    }
+
+    const indexRoute = createRoute({
+      getParentRoute: () => rootRoute,
+      path: '/',
+      component: IndexComponent,
+    })
+
+    const router = createRouter({
+      routeTree: rootRoute.addChildren([indexRoute]),
+      history,
+    })
+
+    render(<RouterProvider router={router} />)
+    await router.load()
+    await screen.findByTestId('unknown-link')
+
+    const unknownLink = screen.getByTestId('unknown-link')
+    unknownLink.click()
+
+    const notFoundComponent = await screen.findByTestId(
+      'not-found',
+      {},
+      { timeout: 1000 },
+    )
+    expect(notFoundComponent).toBeInTheDocument()
+  })
 })

packages/solid-router/src/useBlocker.tsx

@@ -42,8 +42,8 @@ type MakeShouldBlockFnLocationUnion<
 type BlockerResolver<TRouter extends AnyRouter = RegisteredRouter> =
   | {
       status: 'blocked'
-      current: MakeShouldBlockFnLocationUnion<TRouter>
-      next: MakeShouldBlockFnLocationUnion<TRouter>
+      current: MakeShouldBlockFnLocationUnion<TRouter> | undefined
+      next: MakeShouldBlockFnLocationUnion<TRouter> | undefined
       action: HistoryAction
       proceed: () => void
       reset: () => void
@@ -58,8 +58,8 @@ type BlockerResolver<TRouter extends AnyRouter = RegisteredRouter> =
     }
 
 type ShouldBlockFnArgs<TRouter extends AnyRouter = RegisteredRouter> = {
-  current: MakeShouldBlockFnLocationUnion<TRouter>
-  next: MakeShouldBlockFnLocationUnion<TRouter>
+  current: MakeShouldBlockFnLocationUnion<TRouter> | undefined
+  next: MakeShouldBlockFnLocationUnion<TRouter> | undefined
   action: HistoryAction
 }
 
@@ -74,6 +74,7 @@ export type UseBlockerOpts<
   enableBeforeUnload?: boolean | (() => boolean)
   disabled?: boolean
   withResolver?: TWithResolver
+  throwOnUnknownRoute?: boolean
 }
 
 type LegacyBlockerFn = () => Promise<any> | any
@@ -165,6 +166,7 @@ export function useBlocker(
       enableBeforeUnload: true,
       disabled: false,
       withResolver: false,
+      throwOnUnknownRoute: true,
     },
     _resolveBlockerOpts(opts, condition),
   )
@@ -184,14 +186,14 @@ export function useBlocker(
     const blockerFnComposed = async (blockerFnArgs: BlockerFnArgs) => {
       function getLocation(
         location: HistoryLocation,
-      ): AnyShouldBlockFnLocation {
+      ): AnyShouldBlockFnLocation | undefined {
         const parsedLocation = router.parseLocation(location)
         const matchedRoutes = router.getMatchedRoutes(
           parsedLocation.pathname,
           undefined,
         )
         if (matchedRoutes.foundRoute === undefined) {
-          throw new Error(`No route found for location ${location.href}`)
+          return undefined
         }
         return {
           routeId: matchedRoutes.foundRoute.id,
@@ -203,7 +205,18 @@ export function useBlocker(
       }
 
       const current = getLocation(blockerFnArgs.currentLocation)
+      if (!current && props.throwOnUnknownRoute) {
+        throw new Error(
+          `No route found for location ${blockerFnArgs.currentLocation.href}`,
+        )
+      }
+
       const next = getLocation(blockerFnArgs.nextLocation)
+      if (!next && props.throwOnUnknownRoute) {
+        throw new Error(
+          `No route found for location ${blockerFnArgs.nextLocation.href}`,
+        )
+      }
 
       const shouldBlock = await props.shouldBlockFn({
         action: blockerFnArgs.action,

packages/solid-router/tests/useBlocker.test-d.tsx

@@ -106,6 +106,7 @@ test('shouldBlockFn has corrent action', () => {
     .toHaveProperty('shouldBlockFn')
     .parameter(0)
     .toHaveProperty('current')
+    .exclude(undefined)
     .toHaveProperty('routeId')
     .toEqualTypeOf<'__root__' | '/' | '/invoices' | '/invoices/'>()
 
@@ -114,6 +115,7 @@ test('shouldBlockFn has corrent action', () => {
     .toHaveProperty('shouldBlockFn')
     .parameter(0)
     .toHaveProperty('next')
+    .exclude(undefined)
     .toHaveProperty('routeId')
     .toEqualTypeOf<'__root__' | '/' | '/invoices' | '/invoices/'>()
 })