tanstack-router-cache 0.1.0

package/docs/getting-started.md

@@ -0,0 +1,151 @@
+# Getting Started
+
+`tanstack-router-cache` caches selected TanStack Router route views by keeping their rendered route tree mounted while it is hidden. Cached routes can preserve local React state, DOM state, scroll-sensitive UI, expensive list state, and in-progress forms without moving that state into a global store.
+
+## Install
+
+```sh
+npm install tanstack-router-cache
+```
+
+```sh
+bun add tanstack-router-cache
+```
+
+## Migration from TanStack Router
+
+You do not need to change your router instance, route tree, loaders, search params, links, or navigation calls. Replace the outlet for the route branch that should support caching, then opt routes into caching with `staticData.routeCache`.
+
+### 1. Replace the outlet
+
+Before:
+
+```tsx
+import { Outlet } from "@tanstack/react-router";
+
+export function AppShell() {
+  return <Outlet />;
+}
+```
+
+After:
+
+```tsx
+import { RouterCacheOutlet, RouterCacheProvider } from "tanstack-router-cache";
+
+export function AppShell() {
+  return (
+    <RouterCacheProvider maxEntries={8} maxEntriesPerRouteId={2}>
+      <RouterCacheOutlet />
+    </RouterCacheProvider>
+  );
+}
+```
+
+If your app shell has navigation, sidebars, headers, or providers around `Outlet`, keep that structure and replace only the route outlet area:
+
+```tsx
+import { RouterCacheOutlet, RouterCacheProvider } from "tanstack-router-cache";
+
+export function AppShell() {
+  return (
+    <RouterCacheProvider maxEntries={8} maxEntriesPerRouteId={2}>
+      <AppNavigation />
+      <RouterCacheOutlet />
+    </RouterCacheProvider>
+  );
+}
+```
+
+### 2. Opt routes into caching
+
+Regular TanStack Router routes continue to work as before. Add `routeCache: true` only to routes whose mounted view should be retained after navigation.
+
+```tsx
+export const Route = createFileRoute("/customers")({
+  staticData: {
+    routeCache: true,
+  },
+  component: CustomersPage,
+});
+```
+
+Routes without `routeCache: true` are rendered and unmounted by TanStack Router normally.
+
+### 3. Pause route work while hidden
+
+Existing `useEffect` calls still work. Use `useRouteCacheEffect` when an effect should run only while the cached route is visible.
+
+```tsx
+import { useRouteCacheEffect } from "tanstack-router-cache";
+
+function CustomersPage() {
+  useRouteCacheEffect(() => {
+    const controller = new AbortController();
+
+    refreshCustomers({ signal: controller.signal });
+
+    return () => {
+      controller.abort();
+    };
+  }, []);
+
+  return <CustomersTable />;
+}
+```
+
+Use `useRouteCacheActive` when child components need a boolean active state instead of an effect.
+
+## Basic setup
+
+Place `RouterCacheProvider` and `RouterCacheOutlet` where TanStack Router would normally render child routes.
+
+```tsx
+import { RouterCacheOutlet, RouterCacheProvider } from "tanstack-router-cache";
+
+export function AppShell() {
+  return (
+    <RouterCacheProvider maxEntries={8} maxEntriesPerRouteId={2}>
+      <RouterCacheOutlet />
+    </RouterCacheProvider>
+  );
+}
+```
+
+Mark routes that should be cached with `staticData.routeCache`.
+
+```tsx
+export const Route = createFileRoute("/customers")({
+  staticData: {
+    routeCache: true,
+  },
+  component: CustomersPage,
+});
+```
+
+Routes without `routeCache: true` are rendered normally and are removed when TanStack Router unmounts them.
+
+## Route static data
+
+The package augments TanStack Router's `StaticDataRouteOption` type:
+
+```ts
+declare module "@tanstack/react-router" {
+  interface StaticDataRouteOption {
+    routeCache?: boolean;
+  }
+}
+```
+
+Set `routeCache: true` on the route whose rendered view should be retained.
+
+```tsx
+export const Route = createFileRoute("/reports")({
+  staticData: {
+    routeCache: true,
+  },
+  component: ReportsPage,
+});
+```
+
+If multiple child matches are present, the cache manager checks child route static data from deepest to shallowest and uses the deepest retained route data.

package/docs/hooks.md

@@ -0,0 +1,187 @@
+# Hooks
+
+## `useRouterCache`
+
+Controls cached route entries.
+
+```tsx
+import { useRouterCache } from "tanstack-router-cache";
+
+function CacheTools() {
+  const { cachedRoutes, destroy, destroyAll, invalidateWhere, isCached } =
+    useRouterCache();
+
+  return (
+    <button type="button" onClick={() => destroy("/customers")}>
+      Clear customers
+    </button>
+  );
+}
+```
+
+Returns:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `cachedRoutes` | `CachedRoutes` | Current cached route data keyed by normalized pathname. |
+| `destroy` | `(pathname: string | string[]) => void` | Removes one or more cached pathnames. |
+| `destroyAll` | `() => void` | Removes every cached route entry. |
+| `invalidateWhere` | `(predicate: (pathname: string, route: CachedRouteData) => boolean) => string[]` | Removes entries that match a predicate and returns the removed pathnames. |
+| `isCached` | `(pathname: string) => boolean` | Returns whether a normalized pathname currently exists in the cache. |
+
+Example: remove all cached entries for one route id.
+
+```tsx
+const { invalidateWhere } = useRouterCache();
+
+invalidateWhere((_, route) => route.routeId === "/customers/$customerId");
+```
+
+## `useRouteCacheActive`
+
+Returns whether a cached route is currently visible.
+
+```tsx
+import { useRouteCacheActive } from "tanstack-router-cache";
+
+function CustomersPage() {
+  const isActive = useRouteCacheActive();
+
+  return <CustomersTable paused={!isActive} />;
+}
+```
+
+Signature:
+
+```ts
+function useRouteCacheActive(pathname?: string): boolean;
+```
+
+If `pathname` is omitted, the hook uses the current route pathname. Pass a pathname when a parent component needs to observe another cached route.
+
+## `useRouteCacheEffect`
+
+Runs an effect only while the current cached route is visible. Cleanup runs when the route becomes hidden, when dependencies change, and when the component unmounts.
+
+```tsx
+import { useRouteCacheEffect } from "tanstack-router-cache";
+
+function CustomersPage() {
+  useRouteCacheEffect(() => {
+    const controller = new AbortController();
+
+    refreshCustomers({ signal: controller.signal });
+
+    return () => {
+      controller.abort();
+    };
+  }, []);
+
+  return <CustomersTable />;
+}
+```
+
+Signature:
+
+```ts
+function useRouteCacheEffect(
+  activeCallback: React.EffectCallback,
+  deps?: React.DependencyList
+): void;
+```
+
+Use this for polling, subscriptions, observers, expensive timers, or async work that should pause while the route is cached but hidden.
+
+## `useRouteCacheActivity`
+
+Subscribes to active/inactive changes for the current route.
+
+```tsx
+import { useRouteCacheActivity } from "tanstack-router-cache";
+
+function CustomersPage() {
+  useRouteCacheActivity((active) => {
+    if (active) {
+      console.log("Customers became visible");
+    }
+  });
+
+  return <CustomersTable />;
+}
+```
+
+Signature:
+
+```ts
+function useRouteCacheActivity(fn: (active: boolean) => void): void;
+```
+
+`active` is `true` when the route is visible and `false` when it is hidden or removed from the visible route position.
+
+## `useRouteCacheNavigation`
+
+Reports navigation timing for cached-route restores.
+
+```tsx
+import { useRouteCacheNavigation } from "tanstack-router-cache";
+
+function NavigationProgress() {
+  const { activeNavigation, lastCompletedNavigation } =
+    useRouteCacheNavigation();
+
+  if (activeNavigation) {
+    return <Spinner />;
+  }
+
+  return lastCompletedNavigation ? (
+    <span>{Math.round(lastCompletedNavigation.duration)} ms</span>
+  ) : null;
+}
+```
+
+Returns:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `activeNavigation` | `RouteCacheNavigationStart | null` | The current cached navigation, if one is in progress. |
+| `lastCompletedNavigation` | `RouteCacheNavigationComplete | null` | Timing data for the most recent completed cached navigation. |
+
+`RouteCacheNavigationStart`:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `pathname` | `string` | Cached route pathname being restored. |
+| `startedAt` | `number` | `performance.now()` timestamp when cached navigation began. |
+
+`RouteCacheNavigationComplete`:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `pathname` | `string` | Cached route pathname that completed. |
+| `startedAt` | `number` | Start timestamp from the matching navigation. |
+| `visibleAt` | `number` | Timestamp after the cached route became visible. |
+| `paintedAt` | `number` | Timestamp after the next animation frame. |
+| `duration` | `number` | `paintedAt - startedAt`. |
+
+## `useRouteCacheErrorBoundary`
+
+Marks the current route as errored while an error boundary fallback is mounted. Errored routes are removed from the cache so users do not keep returning to a failed cached view.
+
+```tsx
+import { useRouteCacheErrorBoundary } from "tanstack-router-cache";
+
+function RouteErrorFallback() {
+  useRouteCacheErrorBoundary();
+
+  return <p>Something went wrong.</p>;
+}
+```
+
+Signature:
+
+```ts
+function useRouteCacheErrorBoundary(pathname?: string): void;
+```
+
+If `pathname` is omitted, the hook uses the current route pathname.
+

package/docs/types.md

@@ -0,0 +1,37 @@
+# Types
+
+## Exported types
+
+```ts
+export type ActivityMode = "visible" | "hidden";
+
+export type RouteCacheNavigationStart = {
+  pathname: string;
+  startedAt: number;
+};
+
+export type RouteCacheNavigationComplete = RouteCacheNavigationStart & {
+  duration: number;
+  paintedAt: number;
+  visibleAt: number;
+};
+```
+
+The package also uses these cache shapes in public return values:
+
+```ts
+type CachedRouteData = {
+  createdAt?: number;
+  href?: string;
+  lastVisibleAt?: number;
+  routeId?: string;
+  staticData: StaticDataRouteOption;
+  matchId?: string;
+  routerSnapshot?: RouterSnapshot;
+  ready?: boolean;
+};
+
+type CachedRoutes = {
+  [key: string]: CachedRouteData;
+};
+```

package/docs/usage.md

@@ -0,0 +1,11 @@
+# Documentation
+
+Use these pages for the package API and behavior details.
+
+- [Getting started](./getting-started.md): install, provider setup, and route flags.
+- [Components](./components.md): `RouterCacheProvider` and `RouterCacheOutlet`.
+- [Hooks](./hooks.md): cache controls, active-state hooks, lifecycle hooks, navigation timing, and error-boundary integration.
+- [Cache behavior](./cache-behavior.md): eviction, pathname handling, hidden containers, and memory notes.
+- [Debugging](./debugging.md): development debug API and snapshots.
+- [Types](./types.md): exported types and cache data shapes.
+- [Architecture](./architecture.md): provider state, router snapshots, rendering flow, events, and memory model.

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "tanstack-router-cache",
+  "version": "0.1.0",
+  "description": "Route view caching for TanStack Router.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Santiago",
+  "keywords": [
+    "react",
+    "tanstack-router",
+    "router",
+    "route-cache",
+    "route-state",
+    "view-cache"
+  ],
+  "files": [
+    "dist",
+    "docs",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "bun run clean && rolldown -c && tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write",
+    "pack:dry-run": "bun pm pack --dry-run",
+    "prepack": "bun run build",
+    "prepublishOnly": "bun run lint && bun run typecheck"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@tanstack/react-router": ">=1.168.14 <2.0.0",
+    "react": ">=19.0.0 <20.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@biomejs/biome": "2.4.15",
+    "@tanstack/react-router": "1.170.11",
+    "@types/node": "25.9.1",
+    "@types/react": "19.2.16",
+    "@types/react-dom": "19.2.3",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "rolldown": "1.1.0",
+    "typescript": "6.0.3"
+  }
+}