tanstack-router-cache 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Original work Copyright (c) NOW hemengke1997
+Modifications Copyright (c) 2026 Santiago Ramos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# tanstack-router-cache
+
+Route view caching for [`@tanstack/react-router`](https://tanstack.com/router).
+
+`tanstack-router-cache` keeps selected route trees mounted while they are hidden, then restores them when the user navigates back. Use it for tab-like workflows, long forms, filtered lists, scroll positions, and page state that should survive route changes without moving everything into global state.
+
+## Install
+
+```sh
+bun add tanstack-router-cache
+```
+
+```sh
+npm install tanstack-router-cache
+```
+
+## Consumer requirements
+
+Your app should already use React and TanStack Router. This package keeps them as peer dependencies so it does not install a second router or React runtime.
+
+| Package | Supported versions |
+| --- | --- |
+| `react` | `>=19.0.0 <20.0.0` |
+| `react-dom` | Match your React version. |
+| `@tanstack/react-router` | `>=1.168.14 <2.0.0` |
+
+## Maintenance
+
+This package is intended to stay compatible with current TanStack Router 1.x releases. The peer dependency floor is tested against the oldest version supported by the current implementation, while development tracks the latest compatible TanStack Router version.
+
+## Usage
+
+Wrap the route tree that should support retention:
+
+```tsx
+import { RouterCacheOutlet, RouterCacheProvider } from "tanstack-router-cache";
+
+export function RootRoute() {
+  return (
+    <RouterCacheProvider maxEntries={8} maxEntriesPerRouteId={2}>
+      <RouterCacheOutlet />
+    </RouterCacheProvider>
+  );
+}
+```
+
+Enable caching on a route:
+
+```tsx
+export const Route = createFileRoute("/customers")({
+  staticData: {
+    routeCache: true,
+  },
+  component: CustomersPage,
+});
+```
+
+Run work only while a retained route is visible:
+
+```tsx
+import { useRouteCacheEffect } from "tanstack-router-cache";
+
+function CustomersPage() {
+  useRouteCacheEffect(() => {
+    const controller = new AbortController();
+
+    return () => {
+      controller.abort();
+    };
+  }, []);
+
+  return <CustomersTable />;
+}
+```
+
+More usage details are in [docs/usage.md](./docs/usage.md).
+
+## Acknowledgements
+
+This project originated from [`hemengke1997/tanstack-router-keepalive`](https://github.com/hemengke1997/tanstack-router-keepalive). The implementation has since diverged substantially, including current TanStack Router compatibility, cache limits, error handling, navigation lifecycle instrumentation, dependency updates, and memory-focused eviction.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/components/cached-outlet.d.ts

@@ -0,0 +1,8 @@
+import { RouterContextProvider } from "@tanstack/react-router";
+import type { ComponentProps } from "react";
+type CachedOutletProps = {
+    matchId: string;
+    routerSnapshot: ComponentProps<typeof RouterContextProvider>["router"];
+};
+export default function CachedOutlet(props: Readonly<CachedOutletProps>): import("react").JSX.Element;
+export {};

package/dist/components/off-screen-in.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode, type RefObject } from "react";
+import type { ActivityMode } from "../types";
+export type OffScreenInProps = {
+    mode: ActivityMode;
+    children: ReactNode;
+    containerRef?: RefObject<HTMLDivElement | null>;
+    pathname?: string;
+};
+export default function OffScreenIn(props: Readonly<OffScreenInProps>): import("react").JSX.Element;

package/dist/components/off-screen.d.ts

@@ -0,0 +1,4 @@
+import type { OffScreenInProps } from "./off-screen-in";
+export default function OffScreen(props: OffScreenInProps & {
+    pathname: string;
+}): import("react").JSX.Element;

package/dist/components/restore-cached-href.d.ts

@@ -0,0 +1,10 @@
+type RestoreCachedHrefInput = {
+    cachedHref?: string;
+    currentHref?: string;
+    currentPathname: string;
+    isRouteCacheEnabled?: boolean;
+    previousPathname?: string;
+};
+export declare function isBareRouteHref(href: string | undefined, currentPathname: string): boolean;
+export declare function shouldRestoreCachedHref({ cachedHref, currentHref, currentPathname, isRouteCacheEnabled, previousPathname, }: RestoreCachedHrefInput): boolean;
+export {};

package/dist/components/route-cache-manager.d.ts

@@ -0,0 +1,2 @@
+declare function RouteCacheManager(): import("react").JSX.Element;
+export default RouteCacheManager;

package/dist/components/router-cache-outlet.d.ts

@@ -0,0 +1,4 @@
+export type RouterCacheOutletProps = {
+    children?: React.ReactNode;
+};
+export declare function RouterCacheOutlet(props: Readonly<RouterCacheOutletProps>): import("react").JSX.Element;

package/dist/contexts/router-cache.d.ts

@@ -0,0 +1,36 @@
+import type { RouterContextProvider, StaticDataRouteOption } from "@tanstack/react-router";
+import type { ComponentProps, ReactNode } from "react";
+type RouterCacheProviderProps = {
+    cacheScopeKey?: string | number | null;
+    children: ReactNode;
+    defaultCachedRoutes?: CachedRoutes;
+    maxEntries?: number;
+    maxEntriesPerRouteId?: number;
+};
+type RouterSnapshot = ComponentProps<typeof RouterContextProvider>["router"];
+export type CachedRouteData = {
+    createdAt?: number;
+    href?: string;
+    lastVisibleAt?: number;
+    routeId?: string;
+    staticData: StaticDataRouteOption;
+    matchId?: string;
+    routerSnapshot?: RouterSnapshot;
+    ready?: boolean;
+};
+export type CachedRoutes = {
+    [key: string]: CachedRouteData;
+};
+export type RouterCacheContextState = {
+    cachedRoutes: CachedRoutes;
+    erroredRouteCounts: Record<string, number>;
+    setCachedRoutes: (pathname: string, data: CachedRouteData) => void;
+    deleteCachedRoutes: (pathname: string[]) => void;
+    touchCachedRoutes: (pathname: string[]) => void;
+    retainErroredRoute: (pathname: string) => void;
+    releaseErroredRoute: (pathname: string) => void;
+};
+export declare function RouterCacheProvider({ cacheScopeKey, children, defaultCachedRoutes, maxEntries, maxEntriesPerRouteId, }: Readonly<RouterCacheProviderProps>): import("react").JSX.Element;
+export declare function useRouterCacheContext(): RouterCacheContextState;
+export declare function useOptionalRouterCacheContext(): RouterCacheContextState | null;
+export {};

package/dist/dom/dismiss-transient-ui.d.ts

@@ -0,0 +1,3 @@
+export declare function initializeTransientUiTracking(documentObject: Document): void;
+export declare function syncTransientUiRouteActivity(pathname: string, mode: "hidden" | "visible"): void;
+export declare function dismissTransientUi(container: HTMLElement | null, pathname: string): void;

package/dist/hooks/use-event-listener.d.ts

@@ -0,0 +1,36 @@
+import type { ActivityMode, RouteCacheNavigationComplete, RouteCacheNavigationStart } from "../types";
+type Events = {
+    activeChange: [
+        {
+            pathname: string;
+            mode: ActivityMode;
+            callback?: () => void;
+        }
+    ];
+    cachedNavigationCancel: [RouteCacheNavigationStart];
+    cachedNavigationComplete: [RouteCacheNavigationComplete];
+    cachedNavigationStart: [RouteCacheNavigationStart];
+};
+type EventName = keyof Events;
+type EventHandler<TName extends EventName> = (...args: Events[TName]) => void;
+type EventBucket = {
+    [key in EventName]?: EventHandler<key>;
+};
+type EventBuckets = {
+    on?: EventBucket;
+    once?: EventBucket;
+};
+declare class RouterCacheEvent {
+    private static instance;
+    private readonly listeners;
+    private constructor();
+    static getInstance(): RouterCacheEvent;
+    on<TName extends EventName>(eventName: TName, handler: EventHandler<TName>): this;
+    once<TName extends EventName>(eventName: TName, handler: EventHandler<TName>): this;
+    off<TName extends EventName>(eventName: TName, handler: EventHandler<TName>): this;
+    emit<TName extends EventName>(eventName: TName, ...args: Events[TName]): boolean;
+}
+export declare function useEventListener(events?: EventBuckets): {
+    eventListener: RouterCacheEvent;
+};
+export {};

package/dist/hooks/use-route-cache-active.d.ts

@@ -0,0 +1 @@
+export declare function useRouteCacheActive(pathname?: string): boolean;

package/dist/hooks/use-route-cache-activity.d.ts

@@ -0,0 +1 @@
+export declare function useRouteCacheActivity(fn: (active: boolean) => void): void;

package/dist/hooks/use-route-cache-effect.d.ts

@@ -0,0 +1,2 @@
+import type { DependencyList, EffectCallback } from "react";
+export declare function useRouteCacheEffect(activeCallback: EffectCallback, deps?: DependencyList): void;

package/dist/hooks/use-route-cache-error-boundary.d.ts

@@ -0,0 +1 @@
+export declare function useRouteCacheErrorBoundary(pathname?: string): void;

package/dist/hooks/use-route-cache-navigation.d.ts

@@ -0,0 +1,7 @@
+import type { RouteCacheNavigationComplete, RouteCacheNavigationStart } from "../types";
+type RouteCacheNavigationState = {
+    activeNavigation: RouteCacheNavigationStart | null;
+    lastCompletedNavigation: RouteCacheNavigationComplete | null;
+};
+export declare function useRouteCacheNavigation(): RouteCacheNavigationState;
+export {};

package/dist/hooks/use-router-cache-debug.d.ts

@@ -0,0 +1,24 @@
+import type { CachedRoutes } from "../contexts/router-cache";
+type RouterCacheDebugSnapshot = {
+    cachedRoutePathnames: string[];
+    dynamicLookingRouteCount: number;
+    dynamicLookingRoutePathnames: string[];
+    hiddenCachedRouteCount: number;
+    hiddenContainerCount: number;
+    totalCachedRouteCount: number;
+    visiblePathname: string;
+};
+type RouterCacheDebugApi = {
+    getSnapshot: () => RouterCacheDebugSnapshot;
+    lastSnapshot?: RouterCacheDebugSnapshot;
+    refresh: () => RouterCacheDebugSnapshot;
+    setWarningThreshold: (nextThreshold?: number | null) => void;
+    warningThreshold?: number | null;
+};
+declare global {
+    interface Window {
+        __TANSTACK_ROUTER_CACHE_DEBUG__?: RouterCacheDebugApi;
+    }
+}
+export declare function useRouterCacheDebug(cachedRoutes: CachedRoutes, visiblePathname: string): void;
+export {};

package/dist/hooks/use-router-cache.d.ts

@@ -0,0 +1,10 @@
+import type { CachedRouteData } from "../contexts/router-cache";
+type InvalidateWherePredicate = (pathname: string, route: CachedRouteData) => boolean;
+export declare function useRouterCache(): {
+    cachedRoutes: import("..").CachedRoutes;
+    destroy: (pathname: string | string[]) => void;
+    destroyAll: () => void;
+    invalidateWhere: (predicate: InvalidateWherePredicate) => string[];
+    isCached: (pathname: string) => boolean;
+};
+export {};

package/dist/hooks/use-update.d.ts

@@ -0,0 +1 @@
+export declare function useUpdate(): () => void;

package/dist/index.cjs

@@ -0,0 +1,66 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let src_components_router_cache_outlet_tsx = require("./components/router-cache-outlet.tsx");
+let src_contexts_router_cache_tsx = require("./contexts/router-cache.tsx");
+let src_hooks_use_route_cache_active_ts = require("./hooks/use-route-cache-active.ts");
+let src_hooks_use_route_cache_activity_ts = require("./hooks/use-route-cache-activity.ts");
+let src_hooks_use_route_cache_effect_ts = require("./hooks/use-route-cache-effect.ts");
+let src_hooks_use_route_cache_error_boundary_ts = require("./hooks/use-route-cache-error-boundary.ts");
+let src_hooks_use_route_cache_navigation_ts = require("./hooks/use-route-cache-navigation.ts");
+let src_hooks_use_router_cache_ts = require("./hooks/use-router-cache.ts");
+Object.defineProperty(exports, "RouterCacheOutlet", {
+	enumerable: true,
+	get: function() {
+		return src_components_router_cache_outlet_tsx.RouterCacheOutlet;
+	}
+});
+Object.defineProperty(exports, "RouterCacheProvider", {
+	enumerable: true,
+	get: function() {
+		return src_contexts_router_cache_tsx.RouterCacheProvider;
+	}
+});
+Object.defineProperty(exports, "useRouteCacheActive", {
+	enumerable: true,
+	get: function() {
+		return src_hooks_use_route_cache_active_ts.useRouteCacheActive;
+	}
+});
+Object.defineProperty(exports, "useRouteCacheActivity", {
+	enumerable: true,
+	get: function() {
+		return src_hooks_use_route_cache_activity_ts.useRouteCacheActivity;
+	}
+});
+Object.defineProperty(exports, "useRouteCacheEffect", {
+	enumerable: true,
+	get: function() {
+		return src_hooks_use_route_cache_effect_ts.useRouteCacheEffect;
+	}
+});
+Object.defineProperty(exports, "useRouteCacheErrorBoundary", {
+	enumerable: true,
+	get: function() {
+		return src_hooks_use_route_cache_error_boundary_ts.useRouteCacheErrorBoundary;
+	}
+});
+Object.defineProperty(exports, "useRouteCacheNavigation", {
+	enumerable: true,
+	get: function() {
+		return src_hooks_use_route_cache_navigation_ts.useRouteCacheNavigation;
+	}
+});
+Object.defineProperty(exports, "useRouterCache", {
+	enumerable: true,
+	get: function() {
+		return src_hooks_use_router_cache_ts.useRouterCache;
+	}
+});
+var src_types_ts = require("./types.ts");
+Object.keys(src_types_ts).forEach(function(k) {
+	if (k !== "default" && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+		enumerable: true,
+		get: function() {
+			return src_types_ts[k];
+		}
+	});
+});

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { RouterCacheOutlet } from "./components/router-cache-outlet";
+export type { CachedRouteData, CachedRoutes } from "./contexts/router-cache";
+export { RouterCacheProvider } from "./contexts/router-cache";
+export { useRouteCacheActive } from "./hooks/use-route-cache-active";
+export { useRouteCacheActivity } from "./hooks/use-route-cache-activity";
+export { useRouteCacheEffect } from "./hooks/use-route-cache-effect";
+export { useRouteCacheErrorBoundary } from "./hooks/use-route-cache-error-boundary";
+export { useRouteCacheNavigation } from "./hooks/use-route-cache-navigation";
+export { useRouterCache } from "./hooks/use-router-cache";
+export * from "./types";
+declare module "@tanstack/react-router" {
+    interface StaticDataRouteOption {
+        routeCache?: boolean;
+    }
+}

package/dist/index.js

@@ -0,0 +1,10 @@
+import { RouterCacheOutlet } from "./components/router-cache-outlet.tsx";
+import { RouterCacheProvider } from "./contexts/router-cache.tsx";
+import { useRouteCacheActive } from "./hooks/use-route-cache-active.ts";
+import { useRouteCacheActivity } from "./hooks/use-route-cache-activity.ts";
+import { useRouteCacheEffect } from "./hooks/use-route-cache-effect.ts";
+import { useRouteCacheErrorBoundary } from "./hooks/use-route-cache-error-boundary.ts";
+import { useRouteCacheNavigation } from "./hooks/use-route-cache-navigation.ts";
+import { useRouterCache } from "./hooks/use-router-cache.ts";
+export * from "./types.ts";
+export { RouterCacheOutlet, RouterCacheProvider, useRouteCacheActive, useRouteCacheActivity, useRouteCacheEffect, useRouteCacheErrorBoundary, useRouteCacheNavigation, useRouterCache };

package/dist/pathname.d.ts

@@ -0,0 +1 @@
+export declare function normalizeCachedRoutePathname(pathname: string): string;

package/dist/types.d.ts

@@ -0,0 +1,10 @@
+export type ActivityMode = "visible" | "hidden";
+export type RouteCacheNavigationStart = {
+    pathname: string;
+    startedAt: number;
+};
+export type RouteCacheNavigationComplete = RouteCacheNavigationStart & {
+    duration: number;
+    paintedAt: number;
+    visibleAt: number;
+};