clear-react-router 1.7.9 → 1.8.1

package/README.md

@@ -38,23 +38,6 @@ It provides first-class support for:
 
 ## API
 
-### `createRouter(routes)`
-
-Normalizes route configuration. Handles wildcard `*` routes, extracts dynamic params, builds nested paths.
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `path` | `string` | Route path, e.g., `/user/:userId` |
-| `element` | `ReactElement \| () => ReactElement \| LazyComponent` | Component to render |
-| `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 the route's `loader`. Overrides the global `defaultLoaderFallback` set in `Router` |
-| `errorElement` | `ReactElement \| () => ReactElement` | Error fallback for the route. Overrides the global `defaultErrorElement` set in `Router` |
-| `staleTime` | `number` | Time in ms before cached data is considered stale and re-fetched in the background. If not provided, data never expires (cached forever) |
-| `actions` | `({ params, context, invalidate, setContext }) => Record<string, (formData: FormData) => unknown \| Promise<unknown>>` | Defines route actions for data mutations. Actions receive `FormData`, can update context via `setContext`, and can refresh loader data using the router-provided `invalidate`. |
-
 ### `Router`
 
 | Prop | Type | Default | Description |
@@ -64,6 +47,7 @@ Normalizes route configuration. Handles wildcard `*` routes, extracts dynamic pa
 | `animationDuration` | `number` | `optional` | Animation duration in milliseconds (browser default is used if not set) |
 | `defaultLoaderFallback` | `ReactElement \| () => ReactElement` | `optional` | Default loading fallback for every route loader |
 | `defaultErrorElement` | `ReactElement \| () => ReactElement` | `optional` | Default error fallback for every route |
+| `defaultRetry` | `number \| { count: number; delay: number }` | `optional` | Default cache revalidation retry policy for all routes |
 | `beforeLoad` | `({ params, context, redirect, setContext }) => Promise<unknown> \| undefined \| void` | `undefined` | Runs before every navigation. Useful for authentication, analytics, or updating shared context.            |
 | `afterLoad`  | `({ params, context, setContext }) => Promise<void>`  | `undefined` | Runs after every successful navigation. Useful for analytics, page tracking, or other global side effects. |
 | `spinner` | `boolean \| undefined` | `true` | Show a small spinner in the corner while loading data (only when `isAnimated` is enabled) |
@@ -82,9 +66,26 @@ Normalizes route configuration. Handles wildcard `*` routes, extracts dynamic pa
   <Router routes={routes} spinner={false} isAnimated />  {/* disable the spinner */}
 </div>
 ```
-
 > **Note:** When `isAnimated` is enabled, `loaderFallback` is not shown. Instead, a small spinner appears (if `spinner={true}`). On the initial page load, however, the route's loaderFallback is rendered if available.
 
+### `createRouter(routes)`
+
+Normalizes route configuration. Handles wildcard `*` routes, extracts dynamic params, builds nested paths.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path` | `string` | Route path, e.g., `/user/:userId` |
+| `element` | `ReactElement \| () => ReactElement \| LazyComponent` | Component to render |
+| `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 the route's `loader`. Overrides the global `defaultLoaderFallback` set in `Router` |
+| `retry` | `number \| { count: number; delay: number }` | `optional` | Overrides the global cache revalidation retry policy for this route |
+| `errorElement` | `ReactElement \| () => ReactElement` | Error fallback for the route. Overrides the global `defaultErrorElement` set in `Router` |
+| `staleTime` | `number` | Time in ms before cached data is considered stale and re-fetched in the background. If not provided, data never expires (cached forever) |
+| `actions` | `({ params, context, invalidate, setContext }) => Record<string, (formData: FormData) => unknown \| Promise<unknown>>` | Defines route actions for data mutations. Actions receive `FormData`, can update context via `setContext`, and can refresh loader data using the router-provided `invalidate`. |
+
 ### `Link`
 
 Component for client-side navigation with prefetch support.
@@ -125,6 +126,68 @@ import { Router, Link } from 'clear-react-router';
 ```
 **Important**: prefetch="render" should be used sparingly, as it preloads data immediately when the link is rendered, which may cause unnecessary network requests.
 
+## Retry
+
+Sometimes a request may fail because of a temporary network issue or a short-lived server problem. Instead of immediately rendering the error state, you can configure the router to automatically retry loading route data.
+
+### Route-level retry
+
+```tsx
+{
+  path: '/posts',
+  loader: loadPosts,
+  retry: 3,
+}
+```
+
+`retry: 3` means the router will make up to **3 additional attempts** after the initial failed request (up to **4 attempts** in total).
+
+You can also specify a delay between attempts:
+
+```tsx
+{
+  path: '/posts',
+  loader: loadPosts,
+  retry: {
+    count: 3,
+    delay: 500,
+  },
+}
+```
+
+### Global retry
+
+To apply the same retry policy to all routes, use `defaultRetry`:
+
+```tsx
+<Router routes={routes} defaultRetry={2} />
+```
+
+or with a delay:
+
+```tsx
+<Router routes={routes} defaultRetry={{ count: 2, delay: 500 }} />
+```
+
+A route-level `retry` always overrides `defaultRetry`.
+
+### How it works
+
+Unlike many routing libraries, retry is **not limited to the initial loader execution**.
+
+The retry policy is applied to the router's **cache revalidation mechanism**, so it automatically works for every operation that reloads route data, including:
+
+* Initial route loading
+* Cache revalidation
+* `invalidate()`
+* `prefetch()`
+
+This ensures consistent behavior regardless of how the data is being refreshed.
+
+### Why?
+
+The router treats the route loader as the single source of truth for route data. Since every data refresh goes through the same cache revalidation pipeline, retry is configured once and automatically applies everywhere without any additional code.
+
 ### `redirect`
 
 Function provided to `beforeLoad` for programmatic redirection.
@@ -456,10 +519,11 @@ await invalidate('/post/[id]/comment/[id]');
 
 #### Including child routes
 
-To revalidate a single route together with its cached child routes, pass the `withChildren` option:
+To revalidate routes together with their cached child routes, pass the `withChildren` option:
 
 ```tsx
-await invalidate('/posts', { withChildren: true }); // a route, not a route list
+await invalidate('/posts', { withChildren: true });
+await invalidate(['/posts', '/users'], { withChildren: true });
 ```
 
 This will recursively revalidate cached routes inside the route tree.

package/dist/cell.d.ts

@@ -1,10 +1,9 @@
-declare class Cell<T> {
+export declare class Cell<T> {
     private _value;
     constructor(_value: T);
     get value(): T;
     set(action: T | ((prev: T) => T)): void;
 }
-export declare const loaderStateRef: Cell<import("./types/global").LoaderState>;
+export declare const loaderStateRef: Cell<import("./types").LoaderState>;
 export declare const prevPathnameRef: Cell<string>;
 export declare const timestampMap: Map<string, number>;
-export {};

package/dist/components/Link.d.ts

@@ -1,5 +1,5 @@
 import { type ReactElement, type MouseEvent, type CSSProperties } from 'react';
-import { RouterProps } from '../types/global';
+import { RouterProps } from '../types';
 type LinkProps = {
     to: string;
     children: ReactElement<{

package/dist/components/Router.d.ts

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

package/dist/config/routerConfig.d.ts

@@ -1,4 +1,4 @@
-import { ClientRouteItem, RouterProps } from '../types/global';
+import { ClientRouteItem, RouterProps } from '../types';
 declare class RouterConfig {
     routes: RouterProps['routes'];
     prefetch: RouterProps['prefetch'];
@@ -7,6 +7,7 @@ declare class RouterConfig {
     hoverPrefetchDelay: number;
     beforeLoad?: ClientRouteItem['beforeLoad'];
     afterLoad?: ClientRouteItem['afterLoad'];
+    defaultRetry?: RouterProps['defaultRetry'];
     configure(config: Partial<RouterConfig>): void;
 }
 export declare const routerConfig: RouterConfig;

package/dist/constants.d.ts

@@ -1,3 +1,3 @@
-import type { LoaderState } from './types/global.ts';
+import type { LoaderState } from './types';
 export declare const emptyLoaderState: LoaderState;
 export declare const STANDARD_PREFETCH_DELAY = 150;

package/dist/{state/createState.d.ts → create.d.ts}

@@ -1,11 +1,10 @@
 type SetStateAction<T> = ((prevState: T) => T) | T;
 type Listener<T> = (state: T, prevState: T) => void;
-type Store<T> = {
+export type Store<T> = {
     subscribe: (listener: Listener<T>) => () => void;
     getState: () => T;
     setState: (action: SetStateAction<T>) => void;
 };
 export declare const create: <T>(initialState: T) => Store<T>;
 export declare const useGlobalState: <T>({ subscribe, getState, setState }: Store<T>) => readonly [T, (action: SetStateAction<T>) => void];
-export declare const createState: <T>(initialState: T) => () => readonly [T, (action: SetStateAction<T>) => void];
 export {};

package/dist/hooks/useAction.d.ts

@@ -1,6 +1 @@
-type Options = Partial<{
-    onSuccess: (args: unknown) => void;
-    onError: (args: unknown) => void;
-}> | undefined;
-export declare const useAction: (action: string, options?: Options) => (formData: FormData) => Promise<void>;
-export {};
+export declare const useAction: (action: string, options?: import("../types").Options) => (arg: FormData) => Promise<void>;

package/dist/hooks/useBlocker.d.ts

@@ -1,4 +1,4 @@
-import { BlockerState } from '../types/global';
+import { BlockerState } from '../types';
 type UseBlockerReturnValue = {
     state: BlockerState;
     process(): void;

package/dist/hooks/useInvalidate.d.ts

@@ -1,2 +1 @@
-import { invalidate } from '../runtime/invalidate';
-export declare const useInvalidate: () => typeof invalidate;
+export declare const useInvalidate: () => (pathList?: string | string[], options?: import("../types").InvalidateOptions) => Promise<void>;

package/dist/hooks/useLoaderState.d.ts

@@ -1,2 +1,2 @@
-import { LoaderState } from '../types/global';
+import { LoaderState } from '../types';
 export declare const useLoaderState: <T>() => LoaderState<T>;

package/dist/hooks/useNavigate.d.ts

@@ -1,2 +1 @@
-import type { Location } from '../types/global';
-export declare const useNavigate: () => (arg: Location | string | -1) => Promise<void>;
+export declare const useNavigate: () => (arg: import("..").Location | string | -1) => Promise<void>;

package/dist/hooks/useQueryParam.d.ts

@@ -1,2 +1,2 @@
-import { AdapterType } from '../types/global';
-export declare function useQueryParam<T>(field: string, adapter: AdapterType<T>, defaultValue?: T): [T, (arg: T | null) => void];
+import { Adapter } from '../types';
+export declare function useQueryParam<T>(field: string, adapter: Adapter<T>, defaultValue?: T): [T, (arg: T | null) => void];

package/dist/hooks/useSetInitialContext.d.ts

@@ -1 +1,2 @@
-export declare const useSetInitialContext: (initialContext?: Record<string, unknown>) => void;
+import { RouterProps } from '../types';
+export declare const useSetInitialContext: (initialContext?: RouterProps["context"]) => void;

package/dist/hooks/useSetRouterConfig.d.ts

@@ -1,2 +1,2 @@
-import { RouterProps } from '../types/global';
+import { RouterProps } from '../types';
 export declare const useSetRouterConfig: (routerProps: RouterProps) => void;

package/dist/index.d.ts

@@ -14,4 +14,4 @@ export { useSearchParams } from './hooks/useSearchParams';
 export { useFormContext } from './hooks/useFormContext';
 export { adapter } from './utils/adapter';
 export { createRouter } from './utils/utils';
-export type { RouteItem, BlockerState, Location, AdapterType, RouterProps } from './types/global';
+export type { RouteItem, BlockerState, Location, Adapter, RouterProps } from './types';