●Change8

v3.17.0

Breaking Changes
📦 nuxtView on GitHub →
⚠ 3 breaking✨ 9 features🐛 2 fixes🔧 9 symbols

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.

⚠️ Breaking Changes

  • 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.
  • 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.
  • Using definePageMeta more than once in a single file now triggers an error.

Migration Steps

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

✨ New Features

  • Reworked async data layer with support for reactive keys (computed refs, plain refs, or getter functions).
  • Optimized data refetching: multiple components watching the same key now trigger only a single fetch operation.
  • New <NuxtTime> component for SSR-safe time display to prevent hydration mismatches.
  • Enhanced <NuxtErrorBoundary> (now an SFC) exposing 'error' and 'clearError' via template slots and refs.
  • <NuxtLink> now supports a 'trailingSlash' prop for URL formatting control.
  • <NuxtLoadingIndicator> now includes 'hideDelay' and 'resetDelay' props for customization.
  • New '@nuxt/docs' npm package containing raw markdown and YAML documentation content.
  • New 'experimental.enforceModuleCompatibility' flag to throw errors for incompatible modules.
  • New 'addComponentExports' utility for module authors to register all named exports from a file.

🐛 Bug Fixes

  • Resolved hydration mismatches when working with dates using the new <NuxtTime> component.
  • Fixed inconsistent data states across components by sharing underlying refs for identical data fetching keys.

🔧 Affected Symbols

useAsyncDatauseFetchNuxtTimeNuxtErrorBoundaryNuxtLinkNuxtLoadingIndicatordefinePageMetaaddComponentExportsloadNuxtConfig