●Change8

v3.20.0

Breaking Changes
📦 nuxtView on GitHub →
⚠ 2 breaking✨ 10 features🐛 8 fixes⚡ 3 deprecations🔧 10 symbols

Summary

Nuxt 3.20.0 introduces experimental TypeScript plugin support, Vite Environment API compatibility, and enhanced asyncData handling. It also features several developer experience improvements like Youch error pages in dev and new Nuxt Kit utilities.

⚠️ Breaking Changes

  • The 'mergeModels' utility has been removed from auto-imports. If you were relying on it being globally available, you must now import it explicitly or use an alternative.
  • The 'shortPath' property was removed and then added back; ensure your logic doesn't depend on its temporary absence in intermediate dev builds.

Migration Steps

  1. Run 'npx nuxt upgrade --dedupe --channel=v3' to upgrade and clean up dependencies.
  2. Replace any usage of 'nuxt.options._layers' with the 'getLayerDirectories()' utility.
  3. Check for usage of 'mergeModels' and add explicit imports if necessary.
  4. Update any custom modules using 'extend', 'extendConfig', or 'configResolved' hooks to prepare for future removal.

✨ New Features

  • Added 'abortController' option to 'useAsyncData' for better request cancellation control.
  • Experimental support for TypeScript plugins.
  • Added 'setGlobalHead' utility to Nuxt Kit.
  • Support for Vite Environment API (opt-in).
  • New 'declarationPath' option for component registration and 'addComponent'.
  • Added 'extensions' option for 'resolveModule' in Nuxt Kit.
  • Display Youch error pages alongside user error pages during development.
  • Extraction of asyncData handlers to separate chunks for better code splitting.
  • Added 'numeric' and 'relativeStyle' props to 'NuxtTime' for relative time formatting.
  • Support for component auto-imports when used as arguments in the 'h()' function.

🐛 Bug Fixes

  • Preserve URL hashes when redirecting via 'routeRules'.
  • Allow object-format 'href' in '<NuxtLink>'.
  • Prevent native HTML attributes from shadowing '<NuxtLink>' props.
  • Fixed concurrent call safety for 'loadNuxtConfig' in Kit.
  • Use SHA-256 hash for prerender cache keys to improve consistency.
  • Fixed HMR handling for arrays within 'appConfig'.
  • Preserve prerender and Nitro flags during Webpack/Rspack server builds.
  • Ensure root route is preserved during 'isPrerendered' checks.

🔧 Affected Symbols

useAsyncDataresolveModulesetGlobalHeadaddComponentNuxtLinkloadNuxtConfigmergeModelsNuxtTimegetLayerDirectoriesaddServerPlugin

⚡ Deprecations

  • The 'extend', 'extendConfig', and 'configResolved' hooks in schema are now deprecated.
  • Directly accessing 'nuxt.options._layers' is deprecated; use 'getLayerDirectories()' instead.
  • Certain Vite hooks have received deprecation notes in favor of the new Vite Environment API compatibility.