Nuxt · performance

NUXT0094Bound keepalive caches on pages with route params

Finds pages that set definePageMeta({ keepalive }) without max when the route has a dynamic param, such as pages/product/[id].vue, and the page key still includes that param.

Why it happens

Nuxt keys each page by its route path with the params filled in, unless definePageMeta sets a key. keepalive: true reaches Vue's <KeepAlive> as {}, and <KeepAlive> evicts cached instances only when max is set. So every distinct id a user visits leaves a mounted page instance behind, with its watchers, effects and fetched data, and the cache grows until the tab closes. Doctor reads params from the resolved Nuxt pages when the manifest is current, otherwise from definePageMeta path or the file path, including parent directories. It skips params named locale, lang or language, which take a few configured values, and it skips a page whose definePageMeta key is a static value, a function that never reads the route, or a function Doctor cannot follow. A current manifest also identifies custom pages outside the pages directory. keepalive options with exclude are skipped as well; options with include are reported only when the resolved Nuxt runtime is 4.5 or later, which adds opted-in pages to the include set.

Fix

Set keepalive: { max: N } so Vue drops the least recently used instance, or give the page a key that does not read the params so one instance is reused for every value.

Example

Bound the cache for a dynamic page

Before

<!-- app/pages/product/[id].vue -->
<script setup lang="ts">
definePageMeta({
  keepalive: true,
})
</script>

After

<!-- app/pages/product/[id].vue -->
<script setup lang="ts">
definePageMeta({
  keepalive: { max: 5 },
})
</script>

Verify the fix

Run only this rule after editing so the report stays focused on the diagnostic you are closing:

pnpm nuxt doctor --rules nuxt/routing/keepalive-requires-max
Copyright © 2026