` via `createPortal`. `KeepAlive` renders one `containerDivRef` element; `CacheComponent` uses a `useLayoutEffect` to move the currently-active cache div into that container and toggle `.active`/`.inactive` classes on siblings.\n\nThree swap modes, picked from props:\n\n- **`transition`**: mark prev siblings `.inactive`, wait `duration - 40ms`, remove them, then append the new div. Relies on user CSS keying off `.active`/`.inactive`.\n- **`viewTransition`**: wraps the sync swap in `document.startViewTransition(...)`.\n- **default**: synchronous swap inside the same `useLayoutEffect`.\n\nWhen inactive **and** not in `include` / matching `exclude`, `CacheComponent` calls `destroy(cacheKey)` itself — this is how `include`/`exclude` eviction flows back into the parent's state.\n\nA cache node only renders its children once `activatedRef.current` has ever been true, so cached-but-never-visited children are not mounted.\n\n### Context + hooks\n\n`CacheComponentProvider` wraps each cache node's children in `CacheComponentContext`, exposing `{ active, refresh, destroy, destroyAll, destroyOther, getCacheNodes, _cacheKey }`. `_cacheKey` is the private hook used by create-time lifecycle hooks to match `destroy` events.\n\n- `useEffectOnActive` / `useLayoutEffectOnActive` — via `useOnActive`, skip when `!active`, optional `skipMount` to no-op the first render.\n- `useEffectOnCreate` / `useLayoutEffectOnCreate` — via `useOnCreate`, run once, store the returned cleanup, then subscribe to the event bus so cleanup fires on `destroy`/`destroyAll`/`destroyOther`/`refresh` for the matching `_cacheKey`.\n- `useKeepAliveContext` — direct read of the context.\n\n### React version compatibility (`packages/core/src/compat/`)\n\n- `Activity.tsx` feature-detects `React.Activity` (19.2+) and sets `hasNativeActivity`; `MemoizedActivty` delays the `visible`→`hidden` flip by `duration` ms so native Activity plays nicely with the transition swap.\n- `safeStartTransition.ts` falls back to a synchronous call when `startTransition` isn't defined (< React 18).\n- `enableActivity` is off by default. Turning it on changes the semantics of `useEffect` inside children: effects re-run on every activation instead of once at mount.\n\nPeer-deps allow React `>=16.8.0`. README pins the split: use `keepalive-for-react@4.x` for React 18, `@5.x` for React 19.2+. React's `StrictMode` is known-incompatible in dev and must not be used.\n\n### Router adapter (`packages/router/src/components/KeepAliveRouteOutlet/index.tsx`)\n\nTiny component: `activeCacheKey` defaults to `location.pathname + location.search`, and `children` is `useOutlet()` (optionally wrapped in `wrapperComponent`). All other `KeepAliveProps` are forwarded. If you need anything router-specific, add it here — core has no router awareness.\n"
},
{
"path": "LICENSE",
"content": "MIT License\n\nCopyright (c) 2024 Rychen Wong\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "README.md",
"content": "
\n\n## Packages\n\n| Package | Version | Description |\n| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |\n| [keepalive-for-react](./packages/core) | [](https://npmjs.com/package/keepalive-for-react) | Core keepalive functionality |\n| [keepalive-for-react-router](./packages/router) | [](https://npmjs.com/package/keepalive-for-react-router) | React Router integration |\n\n## Features\n\n- Support react-router-dom v6+ or react-router v7+\n- Support React v16+ ~ v18+ (v19.2 Activity component support [v5.0.0])\n- Support Suspense and Lazy import\n- Support ErrorBoundary\n- Support Custom Container\n- Support Switching Animation Transition with className `active` and `inactive`\n- Simply implement, without any extra dependencies and hacking ways\n- Only 6KB minified size\n- Support interrupt state effect when component is not active (v5.0.0)\n\n## Attention\n\n- **Version Compatibility**:\n\n - For React 18, please use `keepalive-for-react@4.x.x`\n - For React 19.2+, please use `keepalive-for-react@5.x.x`\n\n- DO NOT use(\"tab1\");\n\n const tab = useMemo(() => {\n return tabs.find(tab => tab.key === currentTab);\n }, [currentTab]);\n\n return (\n | string | RegExp;\n include?: Array | string | RegExp;\n onBeforeActive?: (activeCacheKey: string) => void;\n customContainerRef?: RefObject;\n cacheNodeClassName?: string;\n containerClassName?: string;\n errorElement?: ComponentType<{\n children: ReactNode;\n }>;\n /**\n * transition default false\n */\n transition?: boolean;\n /**\n * use view transition to animate the component when switching tabs\n * @see https://developer.chrome.com/docs/web-platform/view-transitions/\n */\n viewTransition?: boolean;\n /**\n * transition duration default 200\n */\n duration?: number;\n aliveRef?: RefObject;\n /**\n * max alive time for cache node (second)\n * @default 0 (no limit)\n */\n maxAliveTime?: number | MaxAliveConfig[];\n /**\n * enable Activity component from react 19.2+\n * @default false\n * Attention: if enable Activity component, useEffect will trigger when the component is active\n */\n enableActivity?: boolean;\n}\n\ninterface MaxAliveConfig {\n match: string | RegExp;\n expire: number;\n}\n```\n\n## Hooks\n\n### useEffectOnActive\n\n```tsx\nuseEffectOnActive(() => {\n console.log(\"active\");\n}, []);\n```\n\n### useLayoutEffectOnActive\n\n```tsx\nuseLayoutEffectOnActive(\n () => {\n console.log(\"active\");\n },\n [],\n false,\n);\n// the third parameter is optional, default is false,\n// if true, which means the callback will be skipped when the useLayoutEffect is triggered in first render\n```\n\n### useEffectOnCreate\n\nRun a callback only once when the component is first created (cached), and run the returned cleanup only when the component is destroyed from the cache. Unlike `useEffect(fn, [])`, it will NOT re-run when the cached component is re-activated.\n\n```tsx\nuseEffectOnCreate(() => {\n console.log(\"component created\");\n return () => {\n console.log(\"component destroyed\");\n };\n});\n```\n\n### useLayoutEffectOnCreate\n\nSame as `useEffectOnCreate` but uses `useLayoutEffect` internally. Useful when the create-time logic needs to run synchronously before the browser paints.\n\n```tsx\nuseLayoutEffectOnCreate(() => {\n console.log(\"component created (layout)\");\n return () => {\n console.log(\"component destroyed (layout)\");\n };\n});\n```\n\n### useKeepAliveContext\n\ntype definition\n\n```ts\ninterface KeepAliveContext {\n /**\n * whether the component is active\n */\n active: boolean;\n /**\n * refresh the component\n * @param {string} [cacheKey] - The cache key of the component. If not provided, the current cached component will be refreshed.\n */\n refresh: (cacheKey?: string) => void;\n /**\n * destroy the component\n * @param {string} [cacheKey] - the cache key of the component, if not provided, current active cached component will be destroyed\n */\n destroy: (cacheKey?: string | string[]) => Promise;\n /**\n * destroy all components\n */\n destroyAll: () => Promise;\n /**\n * destroy other components except the provided cacheKey\n * @param {string} [cacheKey] - The cache key of the component. If not provided, destroy all components except the current active cached component.\n */\n destroyOther: (cacheKey?: string) => Promise;\n /**\n * get the cache nodes\n */\n getCacheNodes: () => Array;\n}\n```\n\n```tsx\nconst { active, refresh, destroy, getCacheNodes } = useKeepAliveContext();\n// active is a boolean, true is active, false is inactive\n// refresh is a function, you can call it to refresh the component\n// destroy is a function, you can call it to destroy the component\n// ...\n// getCacheNodes is a function, you can call it to get the cache nodes\n```\n\n### useKeepAliveRef\n\ntype definition\n\n```ts\ninterface KeepAliveRef {\n refresh: (cacheKey?: string) => void;\n destroy: (cacheKey?: string | string[]) => Promise;\n destroyAll: () => Promise;\n destroyOther: (cacheKey?: string) => Promise;\n getCacheNodes: () => Array;\n}\n```\n\n```tsx\nfunction App() {\n const aliveRef = useKeepAliveRef();\n // aliveRef.current is a KeepAliveRef object\n\n // you can call refresh and destroy on aliveRef.current\n aliveRef.current?.refresh();\n // it is not necessary to call destroy manually, KeepAlive will handle it automatically\n aliveRef.current?.destroy();\n\n return {/* ... */} ;\n}\n// or\nfunction AppRouter() {\n const aliveRef = useKeepAliveRef();\n // aliveRef.current is a KeepAliveRef object\n\n // you can call refresh and destroy on aliveRef.current\n aliveRef.current?.refresh();\n aliveRef.current?.destroy();\n return (\"tab1\");\n\n const tab = useMemo(() => {\n return tabs.find(tab => tab.key === currentTab);\n }, [currentTab]);\n\n return (\n | string | RegExp;\n include?: Array | string | RegExp;\n onBeforeActive?: (activeCacheKey: string) => void;\n customContainerRef?: RefObject;\n cacheNodeClassName?: string;\n containerClassName?: string;\n errorElement?: ComponentType<{\n children: ReactNode;\n }>;\n /**\n * 过渡效果 默认false\n */\n transition?: boolean;\n\n /**\n * 使用view transition来过渡组件 默认false\n * @see https://developer.chrome.com/docs/web-platform/view-transitions/\n */\n viewTransition?: boolean;\n\n /**\n * 过渡时间 默认200ms\n */\n duration?: number;\n aliveRef?: RefObject;\n /**\n * 缓存节点最大存活时间 (秒)\n * @default 0 (无限制)\n */\n maxAliveTime?: number | MaxAliveConfig[];\n /**\n * 启用 Activity 组件 from react 19.2+\n * @default false\n * 注意: 如果启用 Activity 组件, useEffect 会在组件激活时触发\n */\n enableActivity?: boolean;\n}\n\ninterface MaxAliveConfig {\n match: string | RegExp;\n expire: number;\n}\n```\n\n## Hooks\n\n### useEffectOnActive\n\n```tsx\nuseEffectOnActive(() => {\n console.log(\"active\");\n}, []);\n```\n\n### useLayoutEffectOnActive\n\n```tsx\nuseLayoutEffectOnActive(\n () => {\n console.log(\"active\");\n },\n [],\n false,\n);\n// 第三个参数是可选的,默认为false,\n// 如果为true,表示在首次渲染时触发useLayoutEffect时会跳过回调\n```\n\n### useEffectOnCreate\n\n只在组件首次创建(加入缓存)时执行一次回调，并在组件从缓存中被销毁时执行返回的清理函数。与 `useEffect(fn, [])` 不同，被缓存的组件再次激活时 **不会** 重新执行。\n\n```tsx\nuseEffectOnCreate(() => {\n console.log(\"组件创建\");\n return () => {\n console.log(\"组件销毁\");\n };\n});\n```\n\n### useLayoutEffectOnCreate\n\n与 `useEffectOnCreate` 行为一致,内部使用 `useLayoutEffect`。适用于需要在浏览器绘制前同步执行创建逻辑的场景。\n\n```tsx\nuseLayoutEffectOnCreate(() => {\n console.log(\"组件创建 (layout)\");\n return () => {\n console.log(\"组件销毁 (layout)\");\n };\n});\n```\n\n### useKeepAliveContext\n\n类型定义\n\n```ts\ninterface KeepAliveContext {\n /**\n * 组件是否处于活动状态\n */\n active: boolean;\n /**\n * 刷新组件\n * @param {string} [cacheKey] - 组件的缓存键。如果未提供，将刷新当前缓存的组件。\n */\n refresh: (cacheKey?: string) => void;\n /**\n * 销毁组件\n * @param {string} [cacheKey] - 组件的缓存键，如果未提供，将销毁当前活动的缓存组件。\n */\n destroy: (cacheKey?: string | string[]) => Promise;\n /**\n * 销毁所有组件\n */\n destroyAll: () => Promise;\n /**\n * 销毁除提供的cacheKey外的其他组件\n * @param {string} [cacheKey] - 组件的缓存键。如果未提供，将销毁除当前活动缓存组件外的所有组件。\n */\n destroyOther: (cacheKey?: string) => Promise;\n /**\n * 获取缓存节点\n */\n getCacheNodes: () => Array;\n}\n```\n\n```tsx\nconst { active, refresh, destroy, getCacheNodes } = useKeepAliveContext();\n// active 是一个布尔值，true表示活动，false表示非活动\n// refresh 是一个函数，你可以调用它来刷新组件\n// destroy 是一个函数，你可以调用它来销毁组件\n// ...\n// getCacheNodes 是一个函数，你可以调用它来获取缓存节点\n```\n\n### useKeepAliveRef\n\n类型定义\n\n```ts\ninterface KeepAliveRef {\n refresh: (cacheKey?: string) => void;\n destroy: (cacheKey?: string | string[]) => Promise;\n destroyAll: () => Promise;\n destroyOther: (cacheKey?: string) => Promise;\n getCacheNodes: () => Array;\n}\n```\n\n```tsx\nfunction App() {\n const aliveRef = useKeepAliveRef();\n // aliveRef.current 是一个 KeepAliveRef 对象\n\n // 你可以在 aliveRef.current 上调用 refresh 和 destroy\n aliveRef.current?.refresh();\n // 通常不需要手动调用 destroy,KeepAlive 会自动处理\n aliveRef.current?.destroy();\n\n return {/* ... */} ;\n}\n// 或者\nfunction AppRouter() {\n const aliveRef = useKeepAliveRef();\n // aliveRef.current 是一个 KeepAliveRef 对象\n\n // 你可以在 aliveRef.current 上调用 refresh 和 destroy\n aliveRef.current?.refresh();\n aliveRef.current?.destroy();\n return Vite + React + TS \n \n \n \n \n \n\n"
},
{
"path": "examples/react-router-dom-simple-starter/package.json",
"content": "{\n \"name\": \"react-router-dom-simple-starter\",\n \"private\": true,\n \"version\": \"0.0.0\",\n \"type\": \"module\",\n \"scripts\": {\n \"dev\": \"vite\",\n \"build\": \"tsc -b && vite build\",\n \"lint\": \"eslint .\",\n \"preview\": \"vite preview\"\n },\n \"dependencies\": {\n \"keepalive-for-react\": \"^5.0.10\",\n \"keepalive-for-react-router\": \"^5.0.7\",\n \"react\": \"^19.2.5\",\n \"react-dom\": \"^19.2.5\",\n \"react-router\": \"^7.10.1\"\n },\n \"devDependencies\": {\n \"@eslint/js\": \"^9.39.1\",\n \"@types/react\": \"^19.2.14\",\n \"@types/react-dom\": \"^19.2.3\",\n \"@vitejs/plugin-react\": \"^4.7.0\",\n \"autoprefixer\": \"^10.4.22\",\n \"eslint\": \"^9.39.1\",\n \"eslint-plugin-react-hooks\": \"^5.2.0\",\n \"eslint-plugin-react-refresh\": \"^0.4.24\",\n \"globals\": \"^15.15.0\",\n \"postcss\": \"^8.5.6\",\n \"tailwindcss\": \"^3.4.18\",\n \"typescript\": \"^5.9.3\",\n \"typescript-eslint\": \"^8.48.1\",\n \"vite\": \"^6.4.1\"\n },\n \"pnpm\": {\n \"onlyBuiltDependencies\": [\n \"esbuild\"\n ]\n }\n}\n"
},
{
"path": "examples/react-router-dom-simple-starter/postcss.config.js",
"content": "export default {\n plugins: {\n tailwindcss: {},\n autoprefixer: {},\n },\n}\n"
},
{
"path": "examples/react-router-dom-simple-starter/src/App.tsx",
"content": "import { Fragment } from \"react\";\nimport { RouterProvider } from \"react-router\";\nimport router from \"./router\";\n\nfunction App() {\n return (\n \n \n );\n}\n\nexport default App;\n"
},
{
"path": "examples/react-router-dom-simple-starter/src/index.css",
"content": "@tailwind base;\n@tailwind components;\n@tailwind utilities;\n\n/* \nkeepalive-for-react animation example\ntransition should be set true to enable animation\nand duration should be set to the animation duration\n*/\n\n.cache-component.active {\n animation: fadeIn 0.3s ease-in-out, slideIn 0.3s ease-in-out;\n}\n\n.cache-component.inactive {\n animation: fadeOut 0.3s ease-in-out, slideOut 0.3s ease-in-out;\n}\n\n@keyframes fadeIn {\n from {\n opacity: 0;\n }\n to {\n opacity: 1;\n }\n}\n\n@keyframes fadeOut {\n from {\n opacity: 1;\n }\n to {\n opacity: 0;\n }\n}\n\n@keyframes slideIn {\n from {\n transform: translateX(-100%);\n }\n to {\n transform: translateX(0);\n }\n}\n\n@keyframes slideOut {\n from {\n transform: translateX(0);\n }\n to {\n transform: translateX(100%);\n }\n}"
},
{
"path": "examples/react-router-dom-simple-starter/src/layout/index.tsx",
"content": "import { useKeepAliveRef } from \"keepalive-for-react\";\nimport KeepAliveRouteOutlet from \"keepalive-for-react-router\";\nimport { ReactNode, Suspense, useEffect, useMemo, useRef } from \"react\";\nimport { Link, useLocation } from \"react-router\";\n\nfunction Layout() {\n const location = useLocation();\n const activePath = location.pathname + location.search;\n const aliveRef = useKeepAliveRef();\n return (\n (null);\n const location = useLocation();\n const scrollHistoryMap = useRef>(new Map());\n\n const activeKey = useMemo(() => {\n return location.pathname + location.search;\n }, [location.pathname, location.search]);\n\n useEffect(() => {\n const divDom = domRef.current;\n if (!divDom) return;\n setTimeout(() => {\n divDom.scrollTo(0, scrollHistoryMap.current.get(activeKey) || 0);\n }, 300); // 300 milliseconds to wait for the animation transition ending\n const onScroll = (e: Event) => {\n const target = e.target as HTMLDivElement;\n if (!target) return;\n scrollHistoryMap.current.set(activeKey, target?.scrollTop || 0);\n };\n divDom?.addEventListener(\"scroll\", onScroll, {\n passive: true,\n });\n return () => {\n divDom?.removeEventListener(\"scroll\", onScroll);\n };\n }, [activeKey]);\n\n return (\n \n {children}\n
\n );\n}\n\nfunction CustomSuspense(props: { children: ReactNode }) {\n const { children } = props;\n return \n ![\"keepalive-for-react](\"./react-keepalive.png\")
\n
\n
\n\n\n KeepAlive for React\n
\nA React KeepAlive component like keep-alive in vue
\n\n[中文](./README.zh_CN.md) | English\n\n[](https://npmjs.com/package/keepalive-for-react) [](https://npmjs.com/package/keepalive-for-react) [![][discord-shield]][discord-link]\n\n## Packages\n\n| Package | Version | Description |\n| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |\n| [keepalive-for-react](./packages/core) | [](https://npmjs.com/package/keepalive-for-react) | Core keepalive functionality |\n| [keepalive-for-react-router](./packages/router) | [](https://npmjs.com/package/keepalive-for-react-router) | React Router integration |\n\n## Features\n\n- Support react-router-dom v6+ or react-router v7+\n- Support React v16+ ~ v18+ (v19.2 Activity component support [v5.0.0])\n- Support Suspense and Lazy import\n- Support ErrorBoundary\n- Support Custom Container\n- Support Switching Animation Transition with className `active` and `inactive`\n- Simply implement, without any extra dependencies and hacking ways\n- Only 6KB minified size\n- Support interrupt state effect when component is not active (v5.0.0)\n\n## Attention\n\n- **Version Compatibility**:\n\n - For React 18, please use `keepalive-for-react@4.x.x`\n - For React 19.2+, please use `keepalive-for-react@5.x.x`\n\n- DO NOT use
\n
\n );\n}\n```\n\nor\n\n```tsx\nimport { useMemo } from \"react\";\n// v6+\nimport { useLocation, useOutlet } from \"react-router-dom\";\n// v7\n// import { useLocation, useOutlet } from \"react-router\";\nimport { KeepAlive, useKeepAliveRef } from \"keepalive-for-react\";\n\nfunction Layout() {\n const location = useLocation();\n const aliveRef = useKeepAliveRef();\n\n const outlet = useOutlet();\n\n // determine which route component to is active\n const currentCacheKey = useMemo(() => {\n return location.pathname + location.search;\n }, [location.pathname, location.search]);\n\n return (\n \n \n \n {outlet} \n \n \n \n
\n );\n}\n```\n\ndetails see [examples/react-router-dom-simple-starter](./examples/react-router-dom-simple-starter)\n\n[](https://stackblitz.com/github/finedaybreak/keepalive-for-react/tree/main/examples/react-router-dom-simple-starter)\n\n### in simple tabs\n\n```bash\nnpm install keepalive-for-react\n```\n\n```tsx\nconst tabs = [\n {\n key: \"tab1\",\n label: \"Tab 1\",\n component: Tab1,\n },\n {\n key: \"tab2\",\n label: \"Tab 2\",\n component: Tab2,\n },\n {\n key: \"tab3\",\n label: \"Tab 3\",\n component: Tab3,\n },\n];\n\nfunction App() {\n const [currentTab, setCurrentTab] = useState\n {/* ... */}\n \n {tab && \n
\n );\n}\n```\n\ndetails see [examples/simple-tabs-starter](./examples/simple-tabs-starter)\n\n[](https://stackblitz.com/github/finedaybreak/keepalive-for-react/tree/main/examples/simple-tabs-starter)\n\n## KeepAlive Props\n\ntype definition\n\n```tsx\ninterface KeepAliveProps {\n // determine which component to is active\n activeCacheKey: string;\n children?: KeepAliveChildren;\n /**\n * max cache count default 10\n */\n max?: number;\n exclude?: Array\n \n
\n
\n\n\n React KeepAlive 组件\n
\n一个类似Vue中keep-alive的React KeepAlive组件
\n\n[English](./README.md) | 中文\n\n[](https://npmjs.com/package/keepalive-for-react) [](https://npmjs.com/package/keepalive-for-react)\n\n## 包信息\n\n| 包名 | 版本 | 描述 |\n| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |\n| [keepalive-for-react](./packages/core) | [](https://npmjs.com/package/keepalive-for-react) | 核心keepalive功能 |\n| [keepalive-for-react-router](./packages/router) | [](https://npmjs.com/package/keepalive-for-react-router) | React Router集成 |\n\n## 特性\n\n- 支持react-router-dom v6+ 或 react-router v7+\n- 支持React v16+ ~ v18+ (v19.2 Activity component support [v5.0.0])\n- 支持Suspense和懒加载导入\n- 支持错误边界\n- 支持自定义容器\n- 支持使用className `active`和`inactive`进行切换动画过渡\n- 简单实现,无需任何额外依赖和hack方式\n- 压缩后仅6KB大小\n- 支持中断state Effect当组件不活动时 (v5.0.0)\n\n## 注意事项\n\n- **版本兼容性**：\n\n - React 18 请使用 `keepalive-for-react@4.x.x`\n - React 19.2+ 请使用 `keepalive-for-react@5.x.x`\n\n- 请勿使用\n
\n );\n}\n```\n\n或者\n\n```tsx\nimport { useMemo } from \"react\";\nimport { useLocation } from \"react-router-dom\";\nimport { KeepAlive, useKeepAliveRef } from \"keepalive-for-react\";\n\nfunction Layout() {\n const location = useLocation();\n const aliveRef = useKeepAliveRef();\n\n const outlet = useOutlet();\n\n // 确定哪个路由组件处于活动状态\n const currentCacheKey = useMemo(() => {\n return location.pathname + location.search;\n }, [location.pathname, location.search]);\n\n return (\n \n \n \n {outlet} \n \n \n \n
\n );\n}\n```\n\n详情请参见 [examples/react-router-dom-simple-starter](./examples/react-router-dom-simple-starter)\n\n[](https://stackblitz.com/github/finedaybreak/keepalive-for-react/tree/main/examples/react-router-dom-simple-starter)\n\n### 在简单标签页中\n\n```bash\nnpm install keepalive-for-react\n```\n\n```tsx\nconst tabs = [\n {\n key: \"tab1\",\n label: \"标签1\",\n component: Tab1,\n },\n {\n key: \"tab2\",\n label: \"标签2\",\n component: Tab2,\n },\n {\n key: \"tab3\",\n label: \"标签3\",\n component: Tab3,\n },\n];\n\nfunction App() {\n const [currentTab, setCurrentTab] = useState\n {/* ... */}\n \n {tab && \n
\n );\n}\n```\n\n详情请参见 [examples/simple-tabs-starter](./examples/simple-tabs-starter)\n\n[](https://stackblitz.com/github/finedaybreak/keepalive-for-react/tree/main/examples/simple-tabs-starter)\n\n## KeepAlive 属性\n\n类型定义\n\n```tsx\ninterface KeepAliveProps {\n // 确定哪个组件处于活动状态\n activeCacheKey: string;\n children?: KeepAliveChildren;\n /**\n * 最大缓存数量 默认10\n */\n max?: number;\n exclude?: Array\n
\n );\n}\n\n// remember the scroll position of the page when switching routes\nfunction MemoScrollTopWrapper(props: { children?: ReactNode }) {\n const { children } = props;\n const domRef = useRef\n \n Home\n \n \n About\n \n \n Counter\n \n \n Counter2\n \n \n NestedA\n \n \n NestedB\n \n
\n \n \n \n
\n \n
\n );\n}\n\nexport default About;\n"
},
{
"path": "examples/react-router-dom-simple-starter/src/pages/counter/index.tsx",
"content": "import { useEffectOnActive, useEffectOnCreate, useKeepAliveContext } from \"keepalive-for-react\";\nimport { useState } from \"react\";\n\nfunction Counter() {\n const [count, setCount] = useState(0);\n const { refresh, active } = useKeepAliveContext();\n\n // useEffectOnActive(() => {\n // console.log(\"Counter is active (OnActive)\", count);\n // return () => {\n // console.log(\"Counter is destroyed (OnActive)\", count);\n // };\n // }, [count]);\n\n useEffectOnCreate(() => {\n console.log(\"Counter is created (OnCreate)\", count);\n return () => {\n console.log(\"Counter is destroyed (_OnCreate)\", count);\n };\n });\n\n return (\n About
\n\n \n
\n \n
\n );\n}\n\nexport default Counter;\n"
},
{
"path": "examples/react-router-dom-simple-starter/src/pages/home/index.tsx",
"content": "import { useEffectOnActive } from \"keepalive-for-react\";\nimport { useRef } from \"react\";\n\nfunction Home() {\n const domRef = useRefCounter
\n\n \n Active: {active ? \"true\" : \"false\"}\n \n
\n {count}
\n \n setCount(count + 1)}\n >\n Increase\n \n setCount(count - 1)}\n >\n Decrease\n \n \n
\n \n
\n );\n}\n\nexport default Home;\n"
},
{
"path": "examples/react-router-dom-simple-starter/src/pages/nested/index.tsx",
"content": "import { Outlet } from \"react-router\";\n\nfunction Nested() {\n return (\n Home
\n\n Welcome to the home page, this is a simple example of how to use keepalive-for-react with react-router-dom.\n
\nInstall
\n\n {`npm install keepalive-for-react react-router-dom`}\n \n {\"./src/layout/index.tsx\"}
\n \n {`\n \n \n {\"Github: \"}\n \n {\"https://github.com/finedaybreak/keepalive-for-react\"}\n \n
\n \n \n
\n );\n}\n\nexport default Nested;\n"
},
{
"path": "examples/react-router-dom-simple-starter/src/pages/nested/nested-a/index.tsx",
"content": "function NestedA() {\n return (\n Nested
\n\n
\n );\n}\n\nexport default NestedA;\n"
},
{
"path": "examples/react-router-dom-simple-starter/src/pages/nested/nested-b/index.tsx",
"content": "function NestedB() {\n return (\n NestedA
\n This is a nested route. It will be cached.
\n \n\n
\n );\n}\n\nexport default NestedB;\n"
},
{
"path": "examples/react-router-dom-simple-starter/src/pages/nocache-counter/index.tsx",
"content": "import { useEffectOnCreate, useKeepAliveContext, useLayoutEffectOnCreate } from \"keepalive-for-react\";\nimport { useState } from \"react\";\n\nfunction NoCacheCounter() {\n const [count, setCount] = useState(0);\n const { refresh, destroy } = useKeepAliveContext();\n useEffectOnCreate(() => {\n console.log(\"NoCacheCounter is created (OnCreate)\", count);\n return () => {\n console.log(\"NoCacheCounter is destroyed (OnCreate)\", count);\n };\n });\n useLayoutEffectOnCreate(() => {\n console.log(\"NoCacheCounter is created (OnLayoutCreate)\", count);\n return () => {\n console.log(\"NoCacheCounter is destroyed (OnLayoutCreate)\", count);\n };\n });\n return (\n NestedB
\n This is a nested route. It will be cached.
\n \n\n
\n );\n}\n\nexport default NoCacheCounter;\n"
},
{
"path": "examples/react-router-dom-simple-starter/src/router/index.tsx",
"content": "import { createBrowserRouter } from \"react-router\";\nimport Layout from \"../layout\";\nimport { lazy } from \"react\";\nimport Nested from \"../pages/nested\";\nimport NestedA from \"../pages/nested/nested-a\";\nimport NestedB from \"../pages/nested/nested-b\";\n// import Home from \"../pages/home\";\n// import About from \"../pages/about\";\n// import Counter from \"../pages/counter\";\n// import NoCacheCounter from \"../pages/nocache-counter\";\n\n// lazy load\nconst Home = lazy(() => import(\"../pages/home\"));\nconst About = lazy(() => import(\"../pages/about\"));\nconst Counter = lazy(() => import(\"../pages/counter\"));\nconst NoCacheCounter = lazy(() => import(\"../pages/nocache-counter\"));\n\nconst router = createBrowserRouter([\n {\n path: \"/\",\n element: Counter (No Cache)
\n{count}
\n \n setCount(count + 1)}\n >\n Increase\n \n setCount(count - 1)}\n >\n Decrease\n \n \n destroy(\"/counter\")}\n >\n Destroy\n \n
\n \n
\n \n {tabs.map(tab => (\n setCurrentTab(tab.key)}\n >\n {tab.label}\n
\n ))}\n \n {/* 虽然 Activity 可以提高性能，但是这里为了有淡出效果，禁用了19.2 的 Activity 组件 */}\n \n {tab && \n
\n \n );\n}\n\nfunction Tab1() {\n const [text, setText] = useState(\"Hello KeepAlive for React\");\n const { refresh } = useKeepAliveContext();\n const { count, increment, decrement } = useCounterStore();\n\n useEffect(() => {\n console.log(\"Tab1 count\", count);\n }, [count]);\n return (\n \n {\n setText(e.target.value);\n }}\n className=\"w-full h-[100px] border border-neutral-200 rounded-md p-[10px] mt-[10px]\"\n >\n\n
\n );\n}\n\nfunction Tab2() {\n const [count, setCount] = useState(0);\n const { refresh, active } = useKeepAliveContext();\n const { count: sharedCount, increment: sharedIncrement, decrement: sharedDecrement } = useCounterStore();\n\n useEffectOnActive(() => {\n console.log(\"Tab2 Counter is active\", count);\n }, [count]);\n\n useEffect(() => {\n console.log(\"Tab2 sharedCount\", sharedCount);\n }, [sharedCount]);\n return (\n Tab1
\n \n This is a demo for keepalive-for-react,\n
you can use it to keep the component alive when switching tabs.\n
\n \n \n
\n {/* shared counter */}\n Shared Counter
\n {count}
\n \n \n \n
\n \n {\"Github: \"}\n \n {\"https://github.com/finedaybreak/keepalive-for-react\"}\n \n
\n \n
\n );\n}\n\nfunction Tab3() {\n const [count, setCount] = useState(0);\n const { refresh, active } = useKeepAliveContext();\n\n useEffectOnActive(() => {\n console.log(\"Tab3 Counter is active\", count, active);\n }, [count]);\n return (\n Tab2
\n \n \n Active: {active ? \"true\" : \"false\"}\n \n
\n {count}
\n \n setCount(count + 1)}\n >\n Increase\n \n setCount(count - 1)}\n >\n Decrease\n \n \n
\n {/* shared counter */}\n Shared Counter
\n {sharedCount}
\n \n \n \n
\n \n
\n );\n}\n\nexport default App;\n"
},
{
"path": "examples/simple-tabs-starter/src/index.css",
"content": "@tailwind base;\n@tailwind components;\n@tailwind utilities;\n\n/* \nkeepalive-for-react animation example\ntransition should be set true to enable animation\nand duration should be set to the animation duration\n*/\n\n.cache-component.active {\n animation:\n fadeIn 0.3s ease-in-out,\n slideIn 0.3s ease-in-out;\n}\n\n.cache-component.inactive {\n animation:\n fadeOut 0.3s ease-in-out,\n slideOut 0.3s ease-in-out;\n}\n\n@keyframes fadeIn {\n from {\n opacity: 0;\n }\n to {\n opacity: 1;\n }\n}\n\n@keyframes fadeOut {\n from {\n opacity: 1;\n }\n to {\n opacity: 0;\n }\n}\n\n@keyframes slideIn {\n from {\n transform: translateX(-100%);\n }\n to {\n transform: translateX(0);\n }\n}\n\n@keyframes slideOut {\n from {\n transform: translateX(0);\n }\n to {\n transform: translateX(100%);\n }\n}\n"
},
{
"path": "examples/simple-tabs-starter/src/main.tsx",
"content": "import { createRoot } from \"react-dom/client\";\nimport App from \"./App.tsx\";\nimport \"./index.css\";\n\ncreateRoot(document.getElementById(\"root\")!).render(Tab3 (no cache)
\n {count}
\n \n setCount(count + 1)}\n >\n Increase\n \n setCount(count - 1)}\n >\n Decrease\n \n \n
\n \n \n
\n
\n\n\n KeepAlive for React\n
\nA React KeepAlive component like keep-alive in vue
\n\n[中文](./README.zh_CN.md) | English\n\n[](https://npmjs.com/package/keepalive-for-react) [](https://npmjs.com/package/keepalive-for-react) [![][discord-shield]][discord-link]\n\n## Packages\n\n| Package | Version | Description |\n| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |\n| [keepalive-for-react](./packages/core) | [](https://npmjs.com/package/keepalive-for-react) | Core keepalive functionality |\n| [keepalive-for-react-router](./packages/router) | [](https://npmjs.com/package/keepalive-for-react-router) | React Router integration |\n\n## Features\n\n- Support react-router-dom v6+ or react-router v7+\n- Support React v16+ ~ v18+ (v19.2 Activity component support [v5.0.0])\n- Support Suspense and Lazy import\n- Support ErrorBoundary\n- Support Custom Container\n- Support Switching Animation Transition with className `active` and `inactive`\n- Simply implement, without any extra dependencies and hacking ways\n- Only 6KB minified size\n- Support interrupt state effect when component is not active (v5.0.0)\n\n## Attention\n\n- **Version Compatibility**:\n\n - For React 18, please use `keepalive-for-react@4.x.x`\n - For React 19.2+, please use `keepalive-for-react@5.x.x`\n\n- DO NOT use
\n
\n );\n}\n```\n\nor\n\n```tsx\nimport { useMemo } from \"react\";\n// v6+\nimport { useLocation, useOutlet } from \"react-router-dom\";\n// v7\n// import { useLocation, useOutlet } from \"react-router\";\nimport { KeepAlive, useKeepAliveRef } from \"keepalive-for-react\";\n\nfunction Layout() {\n const location = useLocation();\n const aliveRef = useKeepAliveRef();\n\n const outlet = useOutlet();\n\n // determine which route component to is active\n const currentCacheKey = useMemo(() => {\n return location.pathname + location.search;\n }, [location.pathname, location.search]);\n\n return (\n \n \n \n {outlet} \n \n \n \n
\n );\n}\n```\n\ndetails see [examples/react-router-dom-simple-starter](./examples/react-router-dom-simple-starter)\n\n[](https://stackblitz.com/github/finedaybreak/keepalive-for-react/tree/main/examples/react-router-dom-simple-starter)\n\n### in simple tabs\n\n```bash\nnpm install keepalive-for-react\n```\n\n```tsx\nconst tabs = [\n {\n key: \"tab1\",\n label: \"Tab 1\",\n component: Tab1,\n },\n {\n key: \"tab2\",\n label: \"Tab 2\",\n component: Tab2,\n },\n {\n key: \"tab3\",\n label: \"Tab 3\",\n component: Tab3,\n },\n];\n\nfunction App() {\n const [currentTab, setCurrentTab] = useState\n {/* ... */}\n \n {tab && \n
\n );\n}\n```\n\ndetails see [examples/simple-tabs-starter](./examples/simple-tabs-starter)\n\n[](https://stackblitz.com/github/finedaybreak/keepalive-for-react/tree/main/examples/simple-tabs-starter)\n\n## KeepAlive Props\n\ntype definition\n\n```tsx\ninterface KeepAliveProps {\n // determine which component to is active\n activeCacheKey: string;\n children?: KeepAliveChildren;\n /**\n * max cache count default 10\n */\n max?: number;\n exclude?: Array\n \n
\n
\n\n\n React KeepAlive 组件\n
\n一个类似Vue中keep-alive的React KeepAlive组件
\n\n[English](./README.md) | 中文\n\n[](https://npmjs.com/package/keepalive-for-react) [](https://npmjs.com/package/keepalive-for-react)\n\n## 包信息\n\n| 包名 | 版本 | 描述 |\n| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |\n| [keepalive-for-react](./packages/core) | [](https://npmjs.com/package/keepalive-for-react) | 核心keepalive功能 |\n| [keepalive-for-react-router](./packages/router) | [](https://npmjs.com/package/keepalive-for-react-router) | React Router集成 |\n\n## 特性\n\n- 支持react-router-dom v6+ 或 react-router v7+\n- 支持React v16+ ~ v18+ (v19.2 Activity component support [v5.0.0])\n- 支持Suspense和懒加载导入\n- 支持错误边界\n- 支持自定义容器\n- 支持使用className `active`和`inactive`进行切换动画过渡\n- 简单实现,无需任何额外依赖和hack方式\n- 压缩后仅6KB大小\n- 支持中断state Effect当组件不活动时 (v5.0.0)\n\n## 注意事项\n\n- **版本兼容性**：\n\n - React 18 请使用 `keepalive-for-react@4.x.x`\n - React 19.2+ 请使用 `keepalive-for-react@5.x.x`\n\n- 请勿使用\n
\n );\n}\n```\n\n或者\n\n```tsx\nimport { useMemo } from \"react\";\nimport { useLocation } from \"react-router-dom\";\nimport { KeepAlive, useKeepAliveRef } from \"keepalive-for-react\";\n\nfunction Layout() {\n const location = useLocation();\n const aliveRef = useKeepAliveRef();\n\n const outlet = useOutlet();\n\n // 确定哪个路由组件处于活动状态\n const currentCacheKey = useMemo(() => {\n return location.pathname + location.search;\n }, [location.pathname, location.search]);\n\n return (\n \n \n \n {outlet} \n \n \n \n
\n );\n}\n```\n\n详情请参见 [examples/react-router-dom-simple-starter](./examples/react-router-dom-simple-starter)\n\n[](https://stackblitz.com/github/finedaybreak/keepalive-for-react/tree/main/examples/react-router-dom-simple-starter)\n\n### 在简单标签页中\n\n```bash\nnpm install keepalive-for-react\n```\n\n```tsx\nconst tabs = [\n {\n key: \"tab1\",\n label: \"标签1\",\n component: Tab1,\n },\n {\n key: \"tab2\",\n label: \"标签2\",\n component: Tab2,\n },\n {\n key: \"tab3\",\n label: \"标签3\",\n component: Tab3,\n },\n];\n\nfunction App() {\n const [currentTab, setCurrentTab] = useState\n {/* ... */}\n \n {tab && \n
\n );\n}\n```\n\n详情请参见 [examples/simple-tabs-starter](./examples/simple-tabs-starter)\n\n[](https://stackblitz.com/github/finedaybreak/keepalive-for-react/tree/main/examples/simple-tabs-starter)\n\n## KeepAlive 属性\n\n类型定义\n\n```tsx\ninterface KeepAliveProps {\n // 确定哪个组件处于活动状态\n activeCacheKey: string;\n children?: KeepAliveChildren;\n /**\n * 最大缓存数量 默认10\n */\n max?: number;\n exclude?: Array\n
\n );\n}\n```\n"
},
{
"path": "packages/router/package.json",
"content": "{\n \"name\": \"keepalive-for-react-router\",\n \"version\": \"5.0.7\",\n \"description\": \"React Router integration for keepalive-for-react\",\n \"homepage\": \"https://github.com/finedaybreak/keepalive-for-react\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git+https://github.com/finedaybreak/keepalive-for-react.git\"\n },\n \"exports\": {\n \".\": {\n \"types\": \"./dist/index.d.ts\",\n \"import\": \"./dist/index.mjs\",\n \"require\": \"./dist/index.cjs\"\n }\n },\n \"main\": \"./dist/index.cjs\",\n \"module\": \"./dist/index.mjs\",\n \"types\": \"./dist/index.d.ts\",\n \"files\": [\n \"dist\"\n ],\n \"type\": \"module\",\n \"scripts\": {\n \"build\": \"tsup\",\n \"clean\": \"rm -rf dist\"\n },\n \"keywords\": [\n \"keepalive\",\n \"keep-alive\",\n \"react keepalive\",\n \"keepalive for react\",\n \"keepalive-for-react\",\n \"keepalive-for-react-router\"\n ],\n \"author\": \"wongyichen\",\n \"license\": \"MIT\",\n \"peerDependencies\": {\n \"keepalive-for-react\": \"^5.0.7\",\n \"react\": \">=16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0\",\n \"react-dom\": \">=16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0\",\n \"react-router\": \">=6.0.0\"\n },\n \"devDependencies\": {\n \"keepalive-for-react\": \"^5.0.7\",\n \"react-router\": \"^7.10.0\"\n }\n}\n"
},
{
"path": "packages/router/src/components/KeepAliveRouteOutlet/index.tsx",
"content": "import { ComponentType, Fragment, ReactNode, useMemo } from \"react\";\nimport { useLocation, useOutlet } from \"react-router\";\nimport { KeepAlive, type KeepAliveProps } from \"keepalive-for-react\";\n\nexport interface KeepAliveRouteOutletProps extends Omit