[Feature/Docs] Best practice for resetting global ErrorBoundary on navigation

[k35o]

Description

I'm currently setting up global error handling by wrapping the <Router /> with a catch-all <ErrorBoundary> (e.g., from react-error-boundary). However, once this outermost error boundary catches an error, navigating away (e.g., clicking the browser's back button) does not clear the error state.

The Context & Pain Point

While route-level errors can be handled by placing an <ErrorBoundary> inside a root Layout component to wrap the <Outlet />, this approach cannot catch errors occurring within the Layout itself or fatal errors during router initialization.

To handle these unhandled exceptions as a last resort, we must place a catch-all boundary outside the <Router>.

Since Funstack Router lacks built-in error handling props, developers naturally use an <ErrorBoundary> outside the router for this safety net. However, being outside the router context means we cannot use hooks like useLocation to reset the boundary.
While we can manually solve this by subscribing to the Navigation API and using NavigationHistoryEntry.key as the reset key, developers migrating from other routing libraries might not realize this pattern, leaving users permanently stuck on the fallback UI.

Proposed Solutions

To improve the Developer Experience regarding global error handling, I suggest the following options:

1. Provide an Official Recipe in the Docs
   Add a section explaining how to properly handle global errors using the Navigation API and useSyncExternalStore. For example:

import { useSyncExternalStore } from 'react';
import { Router } from '@funstack/router';
import { ErrorBoundary } from 'react-error-boundary';

const subscribe = (callback: () => void) => {
  if (typeof window === 'undefined' || !window.navigation) return () => {};
  window.navigation.addEventListener('currententrychange', callback);
  return () => window.navigation.removeEventListener('currententrychange', callback);
};

const getSnapshot = () => window.navigation?.currentEntry?.key || '';
const getServerSnapshot = () => '';

function useNavigationKey() {
  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
}

export default function App() {
  const navKey = useNavigationKey();

  return (
    <ErrorBoundary resetKeys={[navKey]} FallbackComponent={GlobalErrorFallback}>
      <Router routes={routes} />
    </ErrorBoundary>
  );
}

2. Export a Helper Component
   Provide a <GlobalErrorBoundary> wrapper that hooks into the Navigation API internally to automatically reset on location change.

3. Add an errorComponent property to the route API
   Allow defining an error fallback directly in the route configuration.

const routes = [
  route({
    path: '/',
    component: Layout,
    errorComponent: GlobalErrorFallback, // Automatically resets on navigation
    children: [ ... ]
  })
];

I'd love to hear your thoughts on these options. If there is already a better way or a recommended best practice that I might have missed, please let me know!

[uhyo]

Thank you for the feedback!

Actually, the recommended pattern is still an error boundary inside the root layout. The crash of Router itself is considered very unlikely. (I've just fixed a possible cause of this! - #147)

Also, when an error boundary outside the Router activates, and the Router is unmounted as a result, then it no longer intercepts navigation - links or location.reload() would work by actually navigating to another document or full-reloading the current document. User won't get stuck.

[k35o]

@uhyo
Thanks for looking into this!

Even when placing an <ErrorBoundary> inside the Layout to wrap <Outlet />, navigation still doesn't recover from the error state.

Here's a minimal reproduction: https://stackblitz.com/edit/vitejs-vite-5mc5yp16

In this demo, navigating to the About page triggers an error caught by the boundary, but clicking the Home link doesn't clear it. the user remains stuck on the fallback UI.

Would #147 address this case as well? I saw the changes there and wanted to confirm whether it covers ErrorBoundary reset on navigation within the router context.

[uhyo]

@k35o Ah, you still need to use keys to reset the ErrorBoundary!

In the root layout useLocation() can be used for this purpose.

However, currently useLocation() only provides pathname, search and hash which is inconvenient in this case, we are going to add entryKey and entryId to useLocation's return value: #151.

After it is released, below would be the best way for this use case:

function Layout() {
  const { entryId } = useLocation();
  return (
    <div>
      <nav>
        <a href="/">Home</a>
        <a href="/about">About</a>
      </nav>
      <ErrorBoundary resetKeys={[entryId]} fallback={<>error</>}>
        <Outlet />
      </ErrorBoundary>
    </div>
  );
}

[k35o]

@uhyo
That's a huge relief! Not having to manually handle entryKey and the like is exactly what I was hoping for. Thanks!

[uhyo]

@k35o #151 has been released as 1.1.0. Thank you for your feedback 🙂