●Change8

Migrating to Nuxt v3.17.0

Version v3.17.0 introduces 3 breaking changes. This guide details how to update your code.

Released: 4/27/2025

3
Breaking Changes
5
Migration Steps
9
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

useAsyncDatauseFetchNuxtTimeNuxtErrorBoundaryNuxtLinkNuxtLoadingIndicatordefinePageMetaaddComponentExportsloadNuxtConfig

Breaking Changes

●Issue #1

Data fetching now purges cached data when components are unmounted by default. To revert to the previous behavior where data was kept indefinitely, set `experimental.purgeCachedData` to false.

●Issue #2

Calls to useAsyncData or useFetch with the same key now share underlying refs, which may change behavior if your app relied on isolated state for identical keys.

●Issue #3

Using definePageMeta more than once in a single file now triggers an error.

Migration Steps

  1. 1
    Run 'npx nuxi@latest upgrade --dedupe' to update dependencies and refresh the lockfile.
  2. 2
    Test data-heavy pages to ensure 'experimental.purgeCachedData' (enabled by default) does not break expected persistent state.
  3. 3
    Check for multiple 'definePageMeta' calls in single files and consolidate them.
  4. 4
    Review 'runtimeConfig' to ensure the reserved 'app' namespace is not being used.
  5. 5
    If using custom auto-import presets, ensure they do not override core Nuxt presets to avoid new warnings.

Release Summary

Nuxt 3.17 introduces a major rework of the async data layer for better consistency and performance, alongside new built-in components like <NuxtTime> and enhanced error handling.

Need More Details?

View the full release notes and all changes for Nuxt v3.17.0.

View Full Changelog