clear-react-router 1.6.2 → 1.6.4

package/README.md

@@ -2,21 +2,33 @@
 
 A lightweight, type-safe routing library for React applications with nested routes, data loading, navigation blocking, and prefetching.
 
+## Why Clear Router?
+
+Most React routers focus on flexibility and ecosystem integrations.
+Clear Router focuses on predictable navigation with a small, explicit API.
+
+It provides first-class support for:
+
+- Predictable routing
+- Built-in data loading
+- Small API
+
 ## Features
 
-- 🧩 **Nested Routes** - Organize your UI with nested layouts and routes
-- ⚡ **Data Loading** - Built-in loaders with caching and stale-while-revalidate strategy
-- 🔒 **Navigation Blocking** - Prevent accidental navigation with `useBlocker`
-- ✨ **Smooth Animations** - Page transitions with fade effect (customizable duration)
-- 🏗️ **Static Layout** — Keep navbar, footer, and other elements outside the router to avoid unnecessary re-renders
-- 🎯 **Type-safe Redirects** - Redirect from beforeLoad hook
-- 📦 **Prefetching** - Preload data on hover for instant navigation
-- 🚀 **Lazy Loading** - Code-split your routes with dynamic imports for optimal performance
-- 📍 **Scroll Restoration** — Automatically saves and restores scroll position when navigating back to a page (preserves user's scroll position)
-- 🔍 **Typed Query Param** — Type-safe reading and writing of URL query parameters with built-in parsers for strings, numbers, booleans, arrays, and Zod schemas
-- 🎨 **Flexible API** - Use components or hooks as you prefer
-- 📱 **Browser History** - Full support for browser back/forward buttons
-- 🧠 **Context-aware** - Pass and update context through routes
+- **Nested Routes** - Organize your UI with nested layouts and routes
+- **Data Loading** - Built-in loaders with caching and stale-while-revalidate strategy
+- **Navigation Blocking** - Prevent accidental navigation with `useBlocker`
+- **Smooth Animations** - Page transitions with fade effect (customizable duration)
+- **Static Layout** — Keep navbar, footer, and other elements outside the router to avoid unnecessary re-renders
+- **Programmatic Redirects** - Redirect from beforeLoad hook
+- **Cache invalidation** - Manual route invalidation
+- **Prefetching** - Preload data on hover for instant navigation
+- **Lazy Loading** - Code-split your routes with dynamic imports for optimal performance
+- **Scroll Restoration** — Automatically saves and restores scroll position when navigating back to a page (preserves user's scroll position)
+- **Typed Query Param** — Type-safe reading and writing of URL query parameters with built-in parsers for strings, numbers, booleans, arrays, and Zod schemas
+- **Flexible API** - Use components or hooks as you prefer
+- **Browser History** - Full support for browser back/forward buttons
+- **Context-aware** - Pass and update context through routes
 
 ## API
 
@@ -28,8 +40,8 @@ Normalizes route configuration. Handles wildcard `*` routes, extracts dynamic pa
 |----------|------|-------------|
 | `path` | `string` | Route path, e.g., `/user/:userId` |
 | `element` | `ReactElement \| () => ReactElement \| LazyComponent` | Component to render |
-| `loader` | `({ params, context, setContext }) => Promise<unknown>` | Fetch data using route params and context. Can update context via `setContext` |
 | `beforeLoad` | `({ params, context, redirect, setContext }) => Promise<unknown> \| undefined \| void` | Auth checks and redirects. Can update context via `setContext`. `redirect` is provided by the router |
+| `loader` | `({ params, context, setContext }) => Promise<unknown>` | Fetch data using route params and context. Can update context via `setContext` |
 | `afterLoad` | `({ params, context, setContext }) => Promise<void>` | Analytics, side effects after data is loaded. Can update context via `setContext` |
 | `fallback` | `ReactElement \| () => ReactElement` | Loading fallback (for lazy loading) |
 | `loaderFallback` | `ReactElement \| () => ReactElement` | Loading fallback (for loader) |
@@ -43,7 +55,7 @@ The root component that provides routing context to the application. Place stati
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `routeList` | `RouteItem[]` | required | Array of route configurations |
+| `routes` | `RouteItem[]` | required | Array of route configurations |
 | `context` | `object` | `{}` | Initial context (user, theme, etc.) |
 | `children` | `ReactNode` | required | App content (must include `<Router />`) |
 
@@ -71,12 +83,13 @@ Renders the current route's component. Must be placed inside `<RouterProvider>`.
 | `animationDuration` | `number` | `optional` | Animation duration in milliseconds (browser default is used if not set) |
 | `spinner` | `boolean \| undefined` | `true` | Show a small spinner in the corner while loading data (only when `isAnimated` is enabled) |
 | `preserveScroll` | `boolean \| undefined` | `true` | Save and restore scroll position when navigating between pages |
-| `showFallbackIfAnimated` | `boolean \| undefined` | `false` | Show `loaderFallback` even when `isAnimated` is `true` (instead of spinner) |
+| `showFallbackOnAnimation` | `boolean \| undefined` | `false` | Show `loaderFallback` even when `isAnimated` is `true` (instead of spinner) |
 | `prefetch` | `'hover' \| 'render' \| 'viewport' \| 'none'` | `'hover'` | Default prefetch strategy for all `<Link>` components |
 | `hoverPrefetchDelay` | `number` | `150` | Delay in milliseconds before prefetching on hover (only for `'hover'` strategy) |
+| `errorBoundary` | `ComponentType<{ children: ReactNode }>` | `undefined` | Custom error boundary component for catching render errors in route components |
 
 ```
-<RouterProvider routeList={routes}>
+<RouterProvider routes={routes}>
   <Navbar />
   <Router spinner={false} isAnimated />  {/* disable the spinner */}
 </RouterProvider>
@@ -110,7 +123,7 @@ Component for client-side navigation with prefetch support.
 import { RouterProvider, Router, Link } from 'clear-react-router';
 
 // Global prefetch: hover with 100ms delay
-<RouterProvider routeList={routes} prefetch="hover" hoverPrefetchDelay={100}>
+<RouterProvider routes={routes} prefetch="hover" hoverPrefetchDelay={100}>
   <Router />
 </RouterProvider>
 
@@ -204,6 +217,23 @@ const routes = createRouter([
 ]);
 ```
 
+### Error Boundaries
+
+You can provide a custom error boundary to catch rendering errors in route components. This is useful for preventing the entire app from crashing when a specific route fails to render.
+
+```tsx
+import { RouterProvider, Router } from 'clear-react-router';
+import { routes } from './routes';
+import { ErrorBoundary } from './components/ErrorBoundary';
+
+const App = () => (
+    <RouterProvider routes={routes}>
+      <Router errorBoundary={ErrorBoundary} />
+    </RouterProvider>
+  );
+```
+**Note:** The `errorBoundary` prop only catches render-time errors in route components. It does not catch errors in `loader` or `beforeLoad` — those are handled by the router's `errorElement` mechanism.
+
 ## Hooks
 
 ### `useNavigate()`
@@ -245,21 +275,21 @@ Returns current location `{ pathname, search, state }`.
 const { pathname, search, state } = useLocation();
 ```
 
-### `useLoaderState()`
+### `useLoaderState<T>()`
 
 Returns the cached data loaded by the current route's `loader`, along with any errors from `loader` or `beforeLoad`. Data is automatically cached and reused when navigating back to the same route.
 
 **Returns:**
 
 | Property | Type | Description |
-|----------|------|-------------|
-| `data` | `unknown` | The data returned from the route's `loader` |
+|----------|:----:|-------------|
+| `data` | `T` | The data returned from the route's `loader` |
 | `loaderError` | `Error \| null` | Error from the `loader` (if any) |
 | `beforeLoadError` | `Error \| null` | Error from the `beforeLoad` hook (if any) |
 
 ```
-function UserProfile() {
-  const { data, loaderError, beforeLoadError } = useLoaderState();
+const UserProfile = () => {
+  const { data, loaderError, beforeLoadError } = useLoaderState<User>();
 ```
 
 ### Caching behavior:
@@ -273,6 +303,71 @@ function UserProfile() {
 }
 ```
 
+### `useInvalidate()`
+
+Returns a function that marks route data as stale and re-runs the route lifecycle.
+
+Calling `invalidate()` clears the cached loader result for a route and executes both `beforeLoad` and `loader` again. This is useful after mutations or any operation that changes data used by the route.
+
+#### Current route
+
+Invalidate the currently active route:
+
+```tsx
+const invalidate = useInvalidate();
+
+await invalidate();
+```
+
+#### Specific route
+
+You can also invalidate any registered route by passing its pathname:
+
+```tsx
+const invalidate = useInvalidate();
+
+await invalidate('/posts');
+```
+
+The route does not need to be currently active. Its cache will be marked as stale, and the next time it is visited, `beforeLoad` and `loader` will run again.
+
+#### Why use it?
+
+A common use case is refreshing route data after a mutation.
+
+For example, after deleting a post while viewing `/posts/42`, you may want the posts list to be reloaded the next time the user navigates to `/posts`:
+
+```tsx
+const invalidate = useInvalidate();
+
+await deletePost(id);
+await invalidate('/posts');
+```
+
+Likewise, after updating the current page, you can immediately refresh its data:
+
+```tsx
+const invalidate = useInvalidate();
+
+await updateProfile(data);
+await invalidate();
+```
+
+#### Notes
+
+* `invalidate()` re-executes both `beforeLoad` and `loader` for the invalidated route.
+* Cached data is discarded before the new loader starts.
+* When used as an event handler, wrap the call in an arrow function:
+
+```tsx
+<button onClick={() => invalidate()}>
+	Refresh
+</button>
+```
+
+Passing `invalidate` directly (`onClick={invalidate}`) is not supported because React passes a `MouseEvent` object to event handlers.
+
+
 ### `useBlocker(callback)`
 
 Blocks navigation when callback returns `true`.
@@ -370,7 +465,7 @@ type Adapter<T> = {
 | Element | Type | Description |
 |---------|------|-------------|
 | `value` | `T` | The parsed value from the query parameter |
-| `setValue` | `(arg: T | null) => void` | Function to update the query parameter. Null is passed to remove the parameter. |
+| `setValue` | `(arg: T \| null) => void` | Function to update the query parameter. Null is passed to remove the parameter. |
 
 ### Built-in Adapters
 
@@ -489,7 +584,6 @@ function ProductFilter() {
 
 - **Array support** — `getSearchParams` returns `string[]` when multiple values exist for the same key
 - **Functional updates** — Update parameters based on previous state without losing other params
-- **Type-safe** — Proper TypeScript support with overloads
 - **Stable reference** — `setSearchParams` reference is stable and safe to use in `useEffect`
 
 > **Note:** `getSearchParams` returns `string` for single values, `string[]` for multiple values, and `''` if the key is not found.

package/dist/components/Router.d.ts

@@ -1,2 +1,2 @@
 import { RouterProps } from '../types/global';
-export declare const Router: ({ isAnimated, animationDuration, spinner, preserveScroll, showFallbackIfAnimated, prefetch, hoverPrefetchDelay, }: RouterProps) => import("react/jsx-runtime").JSX.Element | null;
+export declare const Router: ({ isAnimated, animationDuration, spinner, preserveScroll, showFallbackOnAnimation, prefetch, hoverPrefetchDelay, errorBoundary: ErrorBoundary, }: RouterProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/RouterProvider.d.ts

@@ -2,8 +2,8 @@ import { ReactNode } from 'react';
 import { RouteItem } from '../types/global';
 type RouteProviderProps = {
     children: ReactNode;
-    routeList: RouteItem[];
+    routes: RouteItem[];
     context?: Record<string, unknown>;
 };
-export declare const RouterProvider: ({ children, routeList, context: initialContext }: RouteProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const RouterProvider: ({ children, routes, context: initialContext }: RouteProviderProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/config/routerConfig.d.ts

@@ -1,7 +1,7 @@
 import { RouterProps } from '../types/global';
 declare class RouterConfig {
     isAnimated: boolean;
-    showFallbackIfAnimated: boolean;
+    showFallbackOnAnimation: boolean;
     prefetch: RouterProps['prefetch'];
     hoverPrefetchDelay: number;
     configure(config: Partial<RouterConfig>): void;

package/dist/context/RouterProviderContext.d.ts

@@ -12,6 +12,7 @@ export type ActionsContextValue = {
     prefetchLoader(arg: string): Promise<void>;
     setContext(arg: object): void;
     restoreScroll(): void;
+    invalidate(path?: string): void;
 };
 export type DataContextValue = {
     context: Record<string, unknown>;

package/dist/hooks/useHandleNavigation.d.ts

@@ -1,7 +1,7 @@
 import { type Dispatch, RefObject, type SetStateAction } from 'react';
 import { BlockerState, LoaderState, Location, RevalidateCacheArgs, RouteItem, RouteItemData, UpdateBlockedRouteProps } from '../types/global';
 type UseHandleNavigation = {
-    routeList: RouteItem[];
+    routes: RouteItem[];
     context: Record<string, unknown>;
     revalidateCache(arg: RevalidateCacheArgs): Promise<unknown>;
     setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
@@ -10,15 +10,17 @@ type UseHandleNavigation = {
         pathname: string;
     }): boolean;
     loaderStateRef: RefObject<LoaderState>;
+    clearTimestamp(path: string): void;
 };
-export declare const useHandleNavigation: ({ routeList, context, revalidateCache, setContext, isCacheItemFresh, loaderStateRef, }: UseHandleNavigation) => {
+export declare const useHandleNavigation: ({ routes, context, revalidateCache, setContext, isCacheItemFresh, loaderStateRef, clearTimestamp, }: UseHandleNavigation) => {
     blockerState: BlockerState;
     updateLocation: (nextLocation: Location) => Promise<void>;
     updateBlockedRoute: ({ type, payload }: UpdateBlockedRouteProps) => void;
     routeItemData: RouteItemData;
     restoreScroll: () => void;
-    currentLoaderFallback: import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | (() => import("react").ReactElement) | undefined;
+    currentLoaderFallback: (import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | (() => import("react").ReactElement)) | undefined;
     isLoading: boolean;
     loaderState: LoaderState;
+    invalidate: (pathname?: string) => Promise<void>;
 };
 export {};

package/dist/hooks/useInvalidate.d.ts

@@ -0,0 +1 @@
+export declare const useInvalidate: () => (path?: string) => void;

package/dist/hooks/useLoader.d.ts

@@ -1,11 +1,11 @@
 import { type Dispatch, type SetStateAction } from 'react';
 import type { LoaderState, RevalidateCacheArgs, RouteItem } from '../types/global';
 type UseLoaderParams = {
-    routeList: RouteItem[];
+    routes: RouteItem[];
     context: Record<string, unknown>;
     setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
 };
-export declare const useLoader: ({ routeList, context, setContext }: UseLoaderParams) => {
+export declare const useLoader: ({ routes, context, setContext }: UseLoaderParams) => {
     prefetchLoader: (pathname: string) => Promise<void>;
     revalidateCache: ({ routeItem, pathname }: RevalidateCacheArgs) => Promise<unknown>;
     isCacheItemFresh: ({ routeItem, pathname }: {
@@ -13,5 +13,6 @@ export declare const useLoader: ({ routeList, context, setContext }: UseLoaderPa
         pathname: string;
     }) => boolean;
     loaderStateRef: import("react").RefObject<LoaderState>;
+    clearTimestamp: (pathname: string) => void;
 };
 export {};

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { useNavigate } from './hooks/useNavigate';
 export { useParams } from './hooks/useParams';
 export { useLocation } from './hooks/useLocation';
 export { useLoaderState } from './hooks/useLoaderState';
+export { useInvalidate } from './hooks/useInvalidate';
 export { useBlocker } from './hooks/useBlocker';
 export { useBeforeUnload } from './hooks/useBeforeUnload';
 export { useRouterContext } from './hooks/useRouterContext';
@@ -13,4 +14,4 @@ export { useSearchParams } from './hooks/useSearchParams';
 export { useHistoricalTrail } from './hooks/useHistoricalTrail';
 export { adapter } from './utils/adapter';
 export { createRouter } from './utils/utils';
-export type { RouteItem, BlockerState, Location, AdapterType } from './types/global';
+export type { RouteItem, BlockerState, Location, AdapterType, RouterProps } from './types/global';

package/dist/index.js

@@ -45,14 +45,15 @@ var require_react_jsx_runtime_production = /* @__PURE__ */ __commonJSMin(((expor
 var import_jsx_runtime = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports = require_react_jsx_runtime_production();
 })))();
-var Provider = ({ children, setContext, context, updateBlockedRoute, updateLocation, prefetchLoader, blockerState, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState }) => {
+var Provider = ({ children, setContext, context, updateBlockedRoute, updateLocation, prefetchLoader, blockerState, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState, invalidate }) => {
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ActionsContext.Provider, {
 		value: {
 			updateLocation,
 			updateBlockedRoute,
 			prefetchLoader,
 			setContext,
-			restoreScroll
+			restoreScroll,
+			invalidate
 		},
 		children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DataContext.Provider, {
 			value: { context },
@@ -124,7 +125,7 @@ function _defineProperty(e, r, t) {
 var RouterConfig = class {
 	constructor() {
 		_defineProperty(this, "isAnimated", false);
-		_defineProperty(this, "showFallbackIfAnimated", false);
+		_defineProperty(this, "showFallbackOnAnimation", false);
 		_defineProperty(this, "prefetch", "hover");
 		_defineProperty(this, "hoverPrefetchDelay", 150);
 	}
@@ -187,8 +188,8 @@ var comparePaths = (el, pathname) => {
 //#endregion
 //#region hooks/useHandleNavigation.ts
 var ALL_LOCATIONS = "*";
-var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, isCacheItemFresh, loaderStateRef }) => {
-	const { isAnimated, showFallbackIfAnimated: showFallback } = routerConfig;
+var useHandleNavigation = ({ routes, context, revalidateCache, setContext, isCacheItemFresh, loaderStateRef, clearTimestamp }) => {
+	const { isAnimated, showFallbackOnAnimation: showFallback } = routerConfig;
 	const [isLoading, setIsLoading] = useState(false);
 	const [blockedRoute, setBlockedRoute] = useState({
 		from: "",
@@ -203,16 +204,16 @@ var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, is
 	const [loaderState, setLoaderState] = useState(emptyLoaderState);
 	const prevPathname = useRef("");
 	const navigationSeq = useRef(0);
-	const scrollMapRef = useLatest(scrollMap);
+	const scrollMapLatest = useLatest(scrollMap);
 	const restoreScroll = useCallback(() => {
-		if (!prevPathname.current || !scrollMapRef.current[prevPathname.current]) return;
+		if (!prevPathname.current || !scrollMapLatest.current[prevPathname.current]) return;
 		requestAnimationFrame(() => {
 			window.scrollTo({
-				top: scrollMapRef.current[prevPathname.current],
+				top: scrollMapLatest.current[prevPathname.current],
 				behavior: "smooth"
 			});
 		});
-	}, [scrollMapRef]);
+	}, [scrollMapLatest]);
 	const navigation = useCallback((nextLocation, routeItem) => {
 		setRouteItemData({
 			routeItem,
@@ -237,21 +238,19 @@ var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, is
 			navigation(nextLocation, routeItem);
 		}
 	}, [navigation, isAnimated]);
-	const navigationHandler = useCallback(async (nextLocation) => {
-		navigationSeq.current = navigationSeq.current + 1;
-		const seq = navigationSeq.current;
-		loaderStateRef.current = emptyLoaderState;
-		const nextItem = routeList.find((el) => el.path === ALL_LOCATIONS || comparePaths(el, nextLocation.pathname));
-		const params = getParamsObject({
-			params: nextItem?.params,
-			pathname: nextLocation.pathname
+	const invalidate = useCallback(async (pathname = routeItemData.location.pathname) => {
+		if (typeof pathname !== "string") return;
+		const routeItem = routes.find((el) => comparePaths(el, pathname));
+		const resultParams = getParamsObject({
+			params: routeItem?.params,
+			pathname
 		});
-		if (nextItem?.beforeLoad) try {
-			const redirect = async (location) => await navigationHandler(typeof location === "string" ? { pathname: location } : location);
-			await nextItem.beforeLoad({
+		clearTimestamp(pathname);
+		try {
+			if (routeItem?.beforeLoad) await routeItem.beforeLoad({
 				context,
-				redirect,
-				params,
+				redirect: () => Promise.resolve(),
+				params: resultParams,
 				setContext
 			});
 			loaderStateRef.current = {
@@ -263,7 +262,50 @@ var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, is
 				...loaderStateRef.current,
 				beforeLoadError: error
 			};
-			return transitionedNavigation(nextLocation, nextItem);
+		}
+		await revalidateCache({
+			routeItem,
+			pathname
+		});
+		if (pathname === routeItemData.location.pathname) setLoaderState(loaderStateRef.current);
+	}, [
+		clearTimestamp,
+		context,
+		loaderStateRef,
+		revalidateCache,
+		routeItemData.location.pathname,
+		routes,
+		setContext
+	]);
+	const navigationHandler = useCallback(async (nextLocation) => {
+		navigationSeq.current = navigationSeq.current + 1;
+		const seq = navigationSeq.current;
+		loaderStateRef.current = emptyLoaderState;
+		const nextItem = routes.find((el) => el.path === ALL_LOCATIONS || comparePaths(el, nextLocation.pathname));
+		const params = getParamsObject({
+			params: nextItem?.params,
+			pathname: nextLocation.pathname
+		});
+		if (nextItem?.beforeLoad) {
+			const redirect = async (location) => await navigationHandler(typeof location === "string" ? { pathname: location } : location);
+			try {
+				await nextItem.beforeLoad({
+					context,
+					redirect,
+					params,
+					setContext
+				});
+				loaderStateRef.current = {
+					...loaderStateRef.current,
+					beforeLoadError: null
+				};
+			} catch (error) {
+				loaderStateRef.current = {
+					...loaderStateRef.current,
+					beforeLoadError: error
+				};
+				return transitionedNavigation(nextLocation, nextItem);
+			}
 		}
 		if (seq !== navigationSeq.current) return;
 		setScrollMap((prevState) => {
@@ -295,7 +337,7 @@ var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, is
 	}, [
 		context,
 		revalidateCache,
-		routeList,
+		routes,
 		transitionedNavigation,
 		setContext,
 		isCacheItemFresh,
@@ -359,19 +401,20 @@ var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, is
 		restoreScroll,
 		currentLoaderFallback,
 		isLoading,
-		loaderState
+		loaderState,
+		invalidate
 	};
 };
 //#endregion
 //#region hooks/useLoader.ts
-var useLoader = ({ routeList, context, setContext }) => {
-	const timestampMapRef = useRef({});
+var useLoader = ({ routes, context, setContext }) => {
+	const timestampMapRef = useRef(/* @__PURE__ */ new Map());
 	const loaderMapRef = useRef({});
 	const loaderStateRef = useRef(emptyLoaderState);
 	const loadingPromises = useRef(/* @__PURE__ */ new Map());
 	const isCacheItemFresh = useCallback(({ routeItem, pathname }) => {
 		if (!routeItem) return true;
-		const currentCacheTimestamp = timestampMapRef.current[pathname];
+		const currentCacheTimestamp = timestampMapRef.current.get(pathname);
 		if (!currentCacheTimestamp) return false;
 		if (!routeItem.staleTime) return true;
 		return Date.now() - currentCacheTimestamp < routeItem.staleTime;
@@ -398,20 +441,13 @@ var useLoader = ({ routeList, context, setContext }) => {
 					context,
 					setContext
 				});
-				timestampMapRef.current = {
-					...timestampMapRef.current,
-					[pathname]: Date.now()
-				};
-				loaderMapRef.current[pathname] = {
-					data: result,
-					loaderError: null,
-					beforeLoadError: null
-				};
+				timestampMapRef.current.set(pathname, Date.now());
 				loaderStateRef.current = {
 					...loaderStateRef?.current,
 					data: result,
 					loaderError: null
 				};
+				loaderMapRef.current[pathname] = loaderStateRef.current;
 			} catch (error) {
 				loaderStateRef.current = {
 					...loaderStateRef?.current,
@@ -431,33 +467,37 @@ var useLoader = ({ routeList, context, setContext }) => {
 	]);
 	return {
 		prefetchLoader: useCallback(async (pathname) => {
-			const item = routeList.find((el) => comparePaths(el, pathname));
+			const item = routes.find((el) => comparePaths(el, pathname));
 			if (item) await revalidateCache({
 				routeItem: item,
 				pathname
 			});
-		}, [revalidateCache, routeList]),
+		}, [revalidateCache, routes]),
 		revalidateCache,
 		isCacheItemFresh,
-		loaderStateRef
+		loaderStateRef,
+		clearTimestamp: useCallback((pathname) => {
+			timestampMapRef.current.delete(pathname);
+		}, [])
 	};
 };
 //#endregion
 //#region components/RouterProvider.tsx
-var RouterProvider = ({ children, routeList, context: initialContext = {} }) => {
+var RouterProvider = ({ children, routes, context: initialContext = {} }) => {
 	const [context, setContext] = useState(initialContext);
-	const { prefetchLoader, revalidateCache, isCacheItemFresh, loaderStateRef } = useLoader({
-		routeList,
+	const { prefetchLoader, revalidateCache, isCacheItemFresh, loaderStateRef, clearTimestamp } = useLoader({
+		routes,
 		context,
 		setContext
 	});
-	const { blockerState, updateLocation, updateBlockedRoute, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState } = useHandleNavigation({
-		routeList,
+	const { blockerState, updateLocation, updateBlockedRoute, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState, invalidate } = useHandleNavigation({
+		routes,
 		context,
 		setContext,
 		revalidateCache,
 		isCacheItemFresh,
-		loaderStateRef
+		loaderStateRef,
+		clearTimestamp
 	});
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Provider, {
 		...useMemo(() => ({
@@ -471,7 +511,8 @@ var RouterProvider = ({ children, routeList, context: initialContext = {} }) =>
 			restoreScroll,
 			currentLoaderFallback,
 			isLoading,
-			loaderState
+			loaderState,
+			invalidate
 		}), [
 			blockerState,
 			context,
@@ -482,7 +523,8 @@ var RouterProvider = ({ children, routeList, context: initialContext = {} }) =>
 			currentLoaderFallback,
 			restoreScroll,
 			isLoading,
-			loaderState
+			loaderState,
+			invalidate
 		]),
 		children
 	});
@@ -548,6 +590,11 @@ var usePreserveScroll = (preserveScroll) => {
 	]);
 };
 //#endregion
+//#region hooks/useSetRouterConfig.ts
+var useSetRouterConfig = (routerProps) => {
+	useEffect(() => routerConfig.configure(routerProps), [routerProps]);
+};
+//#endregion
 //#region components/Spinner.tsx
 var Spinner = () => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { className: "cr-spinner" });
 //#endregion
@@ -557,32 +604,28 @@ var renderElement = (Component) => {
 	return typeof Component === "function" ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Component, {}) : Component;
 };
 //#endregion
-//#region hooks/useSetRouterConfig.ts
-var useSetRouterConfig = (routerProps) => {
-	useEffect(() => routerConfig.configure(routerProps), [routerProps]);
-};
-//#endregion
 //#region components/Router.tsx
-var Router = ({ isAnimated, animationDuration, spinner = true, preserveScroll = true, showFallbackIfAnimated = false, prefetch = "hover", hoverPrefetchDelay = 150 }) => {
-	const { routeItemData: { routeItem }, loaderState, currentLoaderFallback, isLoading } = useNavigationState();
+var EmptyBoundary = ({ children }) => children;
+var Router = ({ isAnimated, animationDuration, spinner = true, preserveScroll = true, showFallbackOnAnimation = false, prefetch = "hover", hoverPrefetchDelay = 150, errorBoundary: ErrorBoundary = EmptyBoundary }) => {
+	const { routeItemData: { routeItem, location }, loaderState, currentLoaderFallback, isLoading } = useNavigationState();
 	usePreserveScroll(preserveScroll);
 	useApplyCustomAnimation(animationDuration);
 	useSetRouterConfig({
 		isAnimated,
-		showFallbackIfAnimated,
+		showFallbackOnAnimation,
 		prefetch,
 		hoverPrefetchDelay
 	});
 	const showErrorElement = !isLoading && Boolean(loaderState.loaderError || loaderState.beforeLoadError);
 	const showSpinner = spinner && isAnimated && isLoading;
 	const loadingContent = !showErrorElement && isLoading;
-	if ((showFallbackIfAnimated || !isAnimated) && loadingContent) return renderElement(currentLoaderFallback);
-	if (!showFallbackIfAnimated && isAnimated && loadingContent) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {});
+	if ((showFallbackOnAnimation || !isAnimated) && loadingContent) return renderElement(currentLoaderFallback);
+	if (!showFallbackOnAnimation && isAnimated && loadingContent) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {});
 	if (!routeItem) return null;
 	if (showErrorElement) return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [renderElement(routeItem.errorElement), showSpinner && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {})] });
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
 		style: { viewTransitionName: "page" },
-		children: [renderElement(routeItem.element) || null, showSpinner && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {})]
+		children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(ErrorBoundary, { children: renderElement(routeItem.element) }, location.pathname), showSpinner && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, {})]
 	});
 };
 //#endregion
@@ -668,11 +711,11 @@ var Link = ({ children, to, prefetch: prefetchLink, hoverPrefetchDelay }) => {
 //#endregion
 //#region hooks/useParams.ts
 var useParams = () => {
-	const { routeItemData: { routeItem } } = useNavigationState();
+	const { routeItemData: { routeItem, location: { pathname } } } = useNavigationState();
 	if (!routeItem) return void 0;
 	return getParamsObject({
 		params: routeItem?.params,
-		pathname: location.pathname
+		pathname
 	});
 };
 //#endregion
@@ -682,6 +725,12 @@ var useLoaderState = () => {
 	return loaderState;
 };
 //#endregion
+//#region hooks/useInvalidate.ts
+var useInvalidate = () => {
+	const { invalidate } = useRouterActions();
+	return invalidate;
+};
+//#endregion
 //#region hooks/useBlocker.ts
 var useBlocker = (blockerFn) => {
 	const { blockerState } = useNavigationState();
@@ -887,4 +936,4 @@ var adapter = {
 	})
 };
 //#endregion
-export { Link, Router, RouterProvider, adapter, createRouter, useBeforeUnload, useBlocker, useHistoricalTrail, useLoaderState, useLocation, useNavigate, useParams, useQueryParam, useRouterContext, useSearchParams };
+export { Link, Router, RouterProvider, adapter, createRouter, useBeforeUnload, useBlocker, useHistoricalTrail, useInvalidate, useLoaderState, useLocation, useNavigate, useParams, useQueryParam, useRouterContext, useSearchParams };

package/dist/provider/Provider.d.ts

@@ -3,5 +3,5 @@ import { type ActionsContextValue, type DataContextValue, type NavigationContext
 type ProviderProps = NavigationContextValue & ActionsContextValue & DataContextValue & {
     children: ReactNode;
 };
-export declare const Provider: ({ children, setContext, context, updateBlockedRoute, updateLocation, prefetchLoader, blockerState, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState, }: ProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Provider: ({ children, setContext, context, updateBlockedRoute, updateLocation, prefetchLoader, blockerState, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState, invalidate, }: ProviderProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/types/global.d.ts

@@ -1,18 +1,19 @@
-import type { ComponentType, Dispatch, ReactElement, SetStateAction } from 'react';
+import type { ComponentType, Dispatch, ReactElement, ReactNode, SetStateAction } from 'react';
 export type LazyComponent = () => Promise<{
     default: ComponentType<unknown>;
 }>;
+type Element = (() => ReactElement) | ReactElement;
 export type ClientRouteItem = {
     path: string;
-    element: (() => ReactElement) | ReactElement | LazyComponent;
+    element: Element | LazyComponent;
     loader?(arg: {
         params: Record<string, string>;
         context: Record<string, unknown>;
         setContext: Dispatch<SetStateAction<Record<string, unknown>>>;
     }): Promise<unknown>;
-    loaderFallback?: (() => ReactElement) | ReactElement;
-    errorElement?: (() => ReactElement) | ReactElement;
-    fallback?: (() => ReactElement) | ReactElement;
+    loaderFallback?: Element;
+    errorElement?: Element;
+    fallback?: Element;
     children?: ClientRouteItem[];
     staleTime?: number;
     beforeLoad?: (arg: {
@@ -28,7 +29,7 @@ export type ClientRouteItem = {
     }) => Promise<void>;
 };
 export type RouteItem = ClientRouteItem & {
-    element: (() => ReactElement) | ReactElement;
+    element: Element;
     params?: {
         key: string;
         value: string;
@@ -67,7 +68,11 @@ export type RouterProps = {
     animationDuration?: number;
     spinner?: boolean;
     preserveScroll?: boolean;
-    showFallbackIfAnimated?: boolean;
+    showFallbackOnAnimation?: boolean;
     prefetch?: 'hover' | 'render' | 'viewport' | 'none';
     hoverPrefetchDelay?: number;
+    errorBoundary?: ComponentType<{
+        children: ReactNode;
+    }>;
 };
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clear-react-router",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "description": "A lightweight, type-safe routing library for React applications",
   "author": "Andrew Bubnov",
   "scripts": {