clear-react-router 1.6.3 → 1.6.4

package/README.md

@@ -20,7 +20,7 @@ It provides first-class support for:
 - **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
+- **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
@@ -55,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 />`) |
 
@@ -83,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>
@@ -122,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>
 
@@ -216,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()`
@@ -285,7 +303,7 @@ const UserProfile = () => {
 }
 ```
 
-### `useInvalidate`
+### `useInvalidate()`
 
 Returns a function that marks route data as stale and re-runs the route lifecycle.
 
@@ -566,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/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>>>;
@@ -12,13 +12,13 @@ type UseHandleNavigation = {
     loaderStateRef: RefObject<LoaderState>;
     clearTimestamp(path: string): void;
 };
-export declare const useHandleNavigation: ({ routeList, context, revalidateCache, setContext, isCacheItemFresh, loaderStateRef, clearTimestamp, }: 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>;

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 }: {

package/dist/index.d.ts

@@ -14,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

@@ -125,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);
 	}
@@ -188,8 +188,8 @@ var comparePaths = (el, pathname) => {
 //#endregion
 //#region hooks/useHandleNavigation.ts
 var ALL_LOCATIONS = "*";
-var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, isCacheItemFresh, loaderStateRef, clearTimestamp }) => {
-	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: "",
@@ -240,7 +240,7 @@ var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, is
 	}, [navigation, isAnimated]);
 	const invalidate = useCallback(async (pathname = routeItemData.location.pathname) => {
 		if (typeof pathname !== "string") return;
-		const routeItem = routeList.find((el) => comparePaths(el, pathname));
+		const routeItem = routes.find((el) => comparePaths(el, pathname));
 		const resultParams = getParamsObject({
 			params: routeItem?.params,
 			pathname
@@ -274,14 +274,14 @@ var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, is
 		loaderStateRef,
 		revalidateCache,
 		routeItemData.location.pathname,
-		routeList,
+		routes,
 		setContext
 	]);
 	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 nextItem = routes.find((el) => el.path === ALL_LOCATIONS || comparePaths(el, nextLocation.pathname));
 		const params = getParamsObject({
 			params: nextItem?.params,
 			pathname: nextLocation.pathname
@@ -337,7 +337,7 @@ var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, is
 	}, [
 		context,
 		revalidateCache,
-		routeList,
+		routes,
 		transitionedNavigation,
 		setContext,
 		isCacheItemFresh,
@@ -407,7 +407,7 @@ var useHandleNavigation = ({ routeList, context, revalidateCache, setContext, is
 };
 //#endregion
 //#region hooks/useLoader.ts
-var useLoader = ({ routeList, context, setContext }) => {
+var useLoader = ({ routes, context, setContext }) => {
 	const timestampMapRef = useRef(/* @__PURE__ */ new Map());
 	const loaderMapRef = useRef({});
 	const loaderStateRef = useRef(emptyLoaderState);
@@ -467,12 +467,12 @@ 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,
@@ -483,15 +483,15 @@ var useLoader = ({ routeList, context, setContext }) => {
 };
 //#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, clearTimestamp } = useLoader({
-		routeList,
+		routes,
 		context,
 		setContext
 	});
 	const { blockerState, updateLocation, updateBlockedRoute, routeItemData, restoreScroll, currentLoaderFallback, isLoading, loaderState, invalidate } = useHandleNavigation({
-		routeList,
+		routes,
 		context,
 		setContext,
 		revalidateCache,
@@ -590,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
@@ -599,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
@@ -710,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

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.3",
+  "version": "1.6.4",
   "description": "A lightweight, type-safe routing library for React applications",
   "author": "Andrew Bubnov",
   "scripts": {