feat: new setting +keepAlive

New setting for preserving page component instances (and thus their
state) across client-side navigation, by wrapping the <Page> component
with Vue's built-in <KeepAlive> component.

Wrapping <slot/> with <KeepAlive> inside a +Layout component cannot
work: <KeepAlive> only caches its direct child component, whereas slot
content is rendered as a Fragment which <KeepAlive> cannot cache. Thus
vike-vue applies <KeepAlive> where it works: directly around the routed
<Page> component.

Usage:
  // pages/+config.ts
  export default {
    keepAlive: true, // or KeepAliveProps, e.g. { max: 10 }
  }

See https://github.com/orgs/vikejs/discussions/3433

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MU13ncNmLi5rz2xySmm5rZ

Author: claude

examples/full/.testRun.ts

@@ -40,6 +40,8 @@ function testRun(cmd: `pnpm run ${'dev' | 'preview'}`) {
 
   testClientOnly()
 
+  testKeepAlive()
+
   const textNoSSR = 'This page is rendered only in the browser'
   {
     const url = '/without-ssr'
@@ -295,6 +297,29 @@ function countMatches(haystack: string, needleRe: RegExp) {
   return (haystack.match(new RegExp(needleRe, 'g')) || []).length
 }
 
+// https://vike.dev/keepAlive
+function testKeepAlive() {
+  test('keepAlive - page state is preserved across client-side navigation', async () => {
+    await page.goto(getServerUrl() + '/keep-alive/first')
+    expect(await page.textContent('h1')).toBe('KeepAlive - First Page')
+    await testCounter()
+
+    await page.click('a:has-text("KeepAlive - Second Page")')
+    await autoRetry(async () => {
+      expect(await page.textContent('h1')).toBe('KeepAlive - Second Page')
+    })
+    await ensureWasClientSideRouted('/pages/keep-alive/first')
+
+    await page.click('a:has-text("KeepAlive - First Page")')
+    await autoRetry(async () => {
+      expect(await page.textContent('h1')).toBe('KeepAlive - First Page')
+    })
+    await ensureWasClientSideRouted('/pages/keep-alive/first')
+    // The counter didn't reset to 0: the page's component instance was preserved by <KeepAlive>
+    expect(await page.textContent('button')).toContain('Counter 1')
+  })
+}
+
 function testClientOnly() {
   const url = '/client-only'
   const textLoading = 'Loading client-only component...'

examples/full/pages/keep-alive/+config.ts

@@ -0,0 +1,6 @@
+import type { Config } from 'vike/types'
+
+// https://vike.dev/keepAlive
+export default {
+  keepAlive: true,
+} satisfies Config

examples/full/pages/keep-alive/first/+Page.vue

@@ -0,0 +1,10 @@
+<template>
+  <h1>KeepAlive - First Page</h1>
+  <p>This page's component instance is preserved across client-side navigation.</p>
+  <Counter />
+  <p><a href="/keep-alive/second">KeepAlive - Second Page</a></p>
+</template>
+
+<script lang="ts" setup>
+import Counter from '../../../components/Counter.vue'
+</script>

examples/full/pages/keep-alive/second/+Page.vue

@@ -0,0 +1,5 @@
+<template>
+  <h1>KeepAlive - Second Page</h1>
+  <p>Navigate back to the first page: its state is preserved.</p>
+  <p><a href="/keep-alive/first">KeepAlive - First Page</a></p>
+</template>

packages/vike-vue/src/+config.ts

@@ -38,6 +38,9 @@ const config = {
       env: { server: true, client: true },
       cumulative: true,
     },
+    keepAlive: {
+      env: { server: true, client: true },
+    },
     title: {
       env: { server: true, client: true },
     },

packages/vike-vue/src/integration/createVueApp.ts

@@ -6,6 +6,7 @@ import {
   createApp,
   createSSRApp,
   h,
+  KeepAlive,
   nextTick,
   shallowRef,
   shallowReactive,
@@ -33,11 +34,21 @@ async function createVueApp(
   if (entryComponentName === 'Page') {
     const entryComponentRef = shallowRef(pageContext.config[entryComponentName])
     const layoutRef = shallowRef(pageContext.config.Layout || [])
+    const keepAliveRef = shallowRef(pageContext.config.keepAlive ?? false)
     onChangePage = (pageContext: PageContext) => {
       entryComponentRef.value = pageContext.config[entryComponentName]
       layoutRef.value = pageContext.config.Layout || []
+      keepAliveRef.value = pageContext.config.keepAlive ?? false
+    }
+    // Wrap <Page> with <KeepAlive>
+    // - It's the only way to make <KeepAlive> work: it cannot be applied inside a +Layout component
+    //   because <KeepAlive> only caches its direct child component, whereas <Layout> receives <Page>
+    //   as slot content (Vue renders slot content as a Fragment which <KeepAlive> cannot cache).
+    const EntryComponent = () => {
+      const keepAlive = keepAliveRef.value
+      if (!keepAlive) return h(entryComponentRef.value)
+      return h(KeepAlive, keepAlive === true ? null : keepAlive, () => h(entryComponentRef.value))
     }
-    const EntryComponent = () => h(entryComponentRef.value)
     RootComponent = () => {
       let RootComp = EntryComponent
       layoutRef.value.forEach((layout) => {

packages/vike-vue/src/types/Config.ts

@@ -3,6 +3,7 @@ import type { TagAttributes } from '../utils/getTagAttributesString.js'
 import type { Viewport, HtmlInjection } from '../integration/onRenderHtml.js'
 import type { ConfigsCumulative } from '../hooks/useConfig/configsCumulative.js'
 import type { Component } from './PageContext.js'
+import type { KeepAliveProps } from 'vue'
 
 // https://vike.dev/pageContext#typescript
 declare global {
@@ -24,6 +25,17 @@ declare global {
        */
       Layout?: Component
 
+      /**
+       * Whether to wrap the `<Page>` component with Vue's built-in [`<KeepAlive>`](https://vuejs.org/guide/built-ins/keep-alive.html) component, preserving page component instances (and thus their state) across client-side navigation.
+       *
+       * Instead of `true`, you can provide `<KeepAlive>` props (e.g. `{ include, exclude, max }`) for controlling which page components are cached.
+       *
+       * @default false
+       *
+       * https://vike.dev/keepAlive
+       */
+      keepAlive?: boolean | KeepAliveProps
+
       /**
        * Set the page's tilte.
        *