fix: trigger navigation guards when keep-alive component is reactivated for different route (#2604)

Fix #2601

Co-authored-by: Eduardo San Martin Morote <posva13@gmail.com>

Author: babu-ch

packages/router/__tests__/guards/onBeforeRouteLeave.spec.ts

@@ -5,15 +5,96 @@ import {
   createRouter,
   createMemoryHistory,
   onBeforeRouteLeave,
+  type RouteRecordRaw,
 } from '../../src'
-import { createApp, defineComponent } from 'vue'
+import { createApp, defineComponent, onActivated, onDeactivated } from 'vue'
+import { mount } from '@vue/test-utils'
 import { vi, describe, expect, it } from 'vitest'
 
 const component = {
   template: '<div>Generic</div>',
 }
 
 describe('onBeforeRouteLeave', () => {
+  it('triggers when shared KeepAlive component is reactivated for a different route', async () => {
+    const routeLeaveSpy = vi.fn()
+    const activatedSpy = vi.fn()
+    const deactivatedSpy = vi.fn()
+    const setupSpy = vi.fn(() => {
+      onBeforeRouteLeave(routeLeaveSpy)
+      onActivated(activatedSpy)
+      onDeactivated(deactivatedSpy)
+      return {}
+    })
+
+    // A shared component used by multiple routes (simulates list pages)
+    const SharedComponent = defineComponent({
+      template: '<div>Shared: {{ $route.path }}</div>',
+      setup: setupSpy,
+    })
+
+    // A different component (simulates detail page)
+    const DetailComponent = defineComponent({
+      template: '<div>Detail</div>',
+    })
+
+    const routes: RouteRecordRaw[] = [
+      { path: '/', component },
+      { path: '/a', component: SharedComponent },
+      { path: '/other', component: DetailComponent },
+      { path: '/b', component: SharedComponent },
+    ]
+
+    const router = createRouter({
+      history: createMemoryHistory(),
+      routes,
+    })
+
+    const wrapper = mount(
+      {
+        template: `
+          <router-view v-slot="{ Component }">
+            <keep-alive>
+              <component :is="Component" />
+            </keep-alive>
+          </router-view>
+        `,
+      },
+      {
+        global: {
+          plugins: [router],
+        },
+      }
+    )
+    await router.isReady()
+
+    // Step 1: Navigate to /a - component mounts and registers guard with /a's record
+    await router.push('/a')
+    expect(routeLeaveSpy).not.toHaveBeenCalled()
+    expect(setupSpy).toHaveBeenCalledTimes(1)
+    expect(activatedSpy).toHaveBeenCalledTimes(1)
+
+    // Step 2: Navigate to another route so SharedComponent is deactivated (kept alive)
+    // Leave guard is called when leaving /a
+    await router.push('/other')
+    expect(deactivatedSpy).toHaveBeenCalledTimes(1)
+    expect(routeLeaveSpy).toHaveBeenCalledTimes(1) // called when leaving /a
+
+    // Step 3: Navigate to /b - SharedComponent is reactivated for a DIFFERENT route
+    // The guard should be re-registered with /b's record
+    await router.push('/b')
+    expect(activatedSpy).toHaveBeenCalledTimes(2)
+    expect(setupSpy).toHaveBeenCalledTimes(1) // still only mounted once (kept alive)
+
+    // Step 4: Leave /b - onBeforeRouteLeave SHOULD be triggered
+    // BUG (before fix): The guard was registered with /a's record, not /b's record
+    // So leaving /b would not trigger the guard
+    await router.push('/')
+    expect(routeLeaveSpy).toHaveBeenCalledTimes(2) // called again when leaving /b
+
+    wrapper.unmount()
+  })
+
   it('removes guards when leaving the route', async () => {
     const spy = vi.fn()
     const WithLeave = defineComponent({

packages/router/__tests__/guards/onBeforeRouteUpdate.spec.ts

@@ -6,9 +6,16 @@ import {
   createMemoryHistory,
   onBeforeRouteUpdate,
   RouterView,
-  RouteRecordRaw,
+  type RouteRecordRaw,
 } from '../../src'
-import { defineComponent, h, ComponentOptions, FunctionalComponent } from 'vue'
+import {
+  defineComponent,
+  h,
+  ComponentOptions,
+  FunctionalComponent,
+  onActivated,
+  onDeactivated,
+} from 'vue'
 import { mount } from '@vue/test-utils'
 import { delay } from '../utils'
 import { vi, describe, expect, it } from 'vitest'
@@ -53,6 +60,71 @@ function factory(
   return { wrapper, router }
 }
 describe('onBeforeRouteUpdate', () => {
+  it('triggers when shared KeepAlive component is reactivated for a different route', async () => {
+    const routeUpdateSpy = vi.fn()
+    const activatedSpy = vi.fn()
+    const deactivatedSpy = vi.fn()
+    const setupSpy = vi.fn(() => {
+      onBeforeRouteUpdate(routeUpdateSpy)
+      onActivated(activatedSpy)
+      onDeactivated(deactivatedSpy)
+      return {}
+    })
+
+    // A shared component used by multiple routes (simulates list pages)
+    const SharedComponent = defineComponent({
+      template: '<div>Shared: {{ $route.path }}</div>',
+      setup: setupSpy,
+    })
+
+    // A different component (simulates detail page)
+    const DetailComponent = defineComponent({
+      template: '<div>Detail</div>',
+    })
+
+    const { router, wrapper } = factory(
+      [
+        { path: '/', component },
+        { path: '/a', component: SharedComponent },
+        { path: '/b', component: SharedComponent },
+      ],
+      {
+        template: `
+          <router-view v-slot="{ Component }">
+            <keep-alive>
+              <component :is="Component" />
+            </keep-alive>
+          </router-view>
+        `,
+      }
+    )
+    await router.isReady()
+
+    // Step 1: Navigate to /a - component mounts and registers guard with /a's record
+    await router.push('/a')
+    expect(routeUpdateSpy).not.toHaveBeenCalled()
+    expect(setupSpy).toHaveBeenCalledTimes(1)
+    expect(activatedSpy).toHaveBeenCalledTimes(1) // activated on mount
+
+    // Step 2: Navigate somewhere else - SharedComponent is deactivated
+    await router.push('/')
+    expect(deactivatedSpy).toHaveBeenCalledTimes(1)
+
+    // Step 3: Navigate to /b - SharedComponent is reactivated for a DIFFERENT route
+    // This is where the bug occurs: guard is added back to /a's record, not /b's
+    await router.push('/b')
+    expect(activatedSpy).toHaveBeenCalledTimes(2) // reactivated
+    expect(setupSpy).toHaveBeenCalledTimes(1) // still only mounted once (kept alive)
+
+    // Step 4: Update query on /b - onBeforeRouteUpdate SHOULD be triggered
+    // BUG (before fix): The guard was registered with /a's record, not /b's record
+    // So when /b updates, the guard is not called
+    await router.push('/b?page=2')
+    expect(routeUpdateSpy).toHaveBeenCalledTimes(1)
+
+    wrapper.unmount()
+  })
+
   it('removes update guards when leaving', async () => {
     const { spy: routeUpdate, Component } = withSpy()
 

packages/router/src/navigationGuards.ts

@@ -16,7 +16,13 @@ import {
   NavigationFailure,
   NavigationRedirectError,
 } from './errors'
-import { ComponentOptions, onUnmounted, onActivated, onDeactivated } from 'vue'
+import {
+  ComponentOptions,
+  onUnmounted,
+  onActivated,
+  onDeactivated,
+  ComputedRef,
+} from 'vue'
 import { inject, getCurrentInstance } from 'vue'
 import { matchedRouteKey } from './injectionSymbols'
 import { RouteRecordNormalized } from './matcher/types'
@@ -25,22 +31,51 @@ import { warn } from './warning'
 import { isSameRouteRecord } from './location'
 
 function registerGuard(
-  record: RouteRecordNormalized,
+  activeRecordRef: ComputedRef<RouteRecordNormalized | undefined>,
   name: 'leaveGuards' | 'updateGuards',
   guard: NavigationGuard
 ) {
+  const record = activeRecordRef.value
+  if (!record) {
+    if (__DEV__) {
+      const fnName =
+        name === 'updateGuards' ? 'onBeforeRouteUpdate' : 'onBeforeRouteLeave'
+      warn(
+        `No active route record was found when calling \`${fnName}()\`. ` +
+          `Make sure you call this function inside a component child of <router-view>. ` +
+          `Maybe you called it inside of App.vue?`
+      )
+    }
+    return
+  }
+
+  // Track the current record the guard is registered with
+  let currentRecord = record
+
   const removeFromList = () => {
-    record[name].delete(guard)
+    currentRecord[name].delete(guard)
   }
 
   onUnmounted(removeFromList)
   onDeactivated(removeFromList)
 
   onActivated(() => {
-    record[name].add(guard)
+    // When reactivated, check if the active record has changed (e.g., keep-alive
+    // component reactivated for a different route). If so, register with the new record.
+    const newRecord = activeRecordRef.value
+    if (__DEV__ && !newRecord) {
+      warn(
+        'No active route record was found when reactivating component with navigation guard. ' +
+          'This is likely a bug in vue-router. Please report it.'
+      )
+    }
+    if (newRecord) {
+      currentRecord = newRecord
+    }
+    currentRecord[name].add(guard)
   })
 
-  record[name].add(guard)
+  currentRecord[name].add(guard)
 }
 
 /**
@@ -58,21 +93,13 @@ export function onBeforeRouteLeave(leaveGuard: NavigationGuard) {
     return
   }
 
-  const activeRecord: RouteRecordNormalized | undefined = inject(
+  const activeRecordRef = inject(
     matchedRouteKey,
     // to avoid warning
     {} as any
-  ).value
-
-  if (!activeRecord) {
-    __DEV__ &&
-      warn(
-        'No active route record was found when calling `onBeforeRouteLeave()`. Make sure you call this function inside a component child of <router-view>. Maybe you called it inside of App.vue?'
-      )
-    return
-  }
+  ) as ComputedRef<RouteRecordNormalized | undefined>
 
-  registerGuard(activeRecord, 'leaveGuards', leaveGuard)
+  registerGuard(activeRecordRef, 'leaveGuards', leaveGuard)
 }
 
 /**
@@ -90,21 +117,13 @@ export function onBeforeRouteUpdate(updateGuard: NavigationGuard) {
     return
   }
 
-  const activeRecord: RouteRecordNormalized | undefined = inject(
+  const activeRecordRef = inject(
     matchedRouteKey,
     // to avoid warning
     {} as any
-  ).value
-
-  if (!activeRecord) {
-    __DEV__ &&
-      warn(
-        'No active route record was found when calling `onBeforeRouteUpdate()`. Make sure you call this function inside a component child of <router-view>. Maybe you called it inside of App.vue?'
-      )
-    return
-  }
+  ) as ComputedRef<RouteRecordNormalized | undefined>
 
-  registerGuard(activeRecord, 'updateGuards', updateGuard)
+  registerGuard(activeRecordRef, 'updateGuards', updateGuard)
 }
 
 export function guardToPromiseFn(