This section documents version-specific API changes in Nuxt v4.4.8 — prioritizing recent major/minor releases where breaking changes and renamed APIs are most likely to differ from pre-trained knowledge.
-
BREAKING: statusCode → status, statusMessage → statusText — Renamed in v4.3 for Web API naming conventions and Nitro v3 alignment source
-
NEW: createUseFetch(options | function) — Factory function to create custom instances of useFetch with default options, new in v4.4 source
-
NEW: createUseAsyncData(options | function) — Factory function for custom useAsyncData instances, new in v4.4 source
-
BREAKING: app/ directory — Nuxt 4.0 changes default project structure from root-level directories to app/ folder; existing structure still works but new projects use app/components/, app/pages/, etc. source
-
BREAKING: Separate TypeScript projects — Nuxt 4.0 now creates distinct TypeScript contexts for app code, server code, shared/, and builder code via separate tsconfig.app.json, tsconfig.server.json, etc.; only one root tsconfig.json needed source
-
NEW: useAnnouncer() composable — New in v4.4 for announcing dynamic in-page changes (form submissions, loading states) to screen readers via polite() and assertive() methods source
-
NEW: <NuxtAnnouncer> component — Renders ARIA live regions for screen reader announcements, paired with useAnnouncer(), new in v4.4 source
-
NEW: Layout props in definePageMeta — Nuxt 4.4 allows passing typed props directly to layouts via definePageMeta({ layout: { name: 'panel', props: { sidebar: true } } }) source
-
BREAKING: Multiple useAsyncData calls with same key now auto-share data — Nuxt 4.0 changed behaviour so components using the same useAsyncData key automatically share data; old code expecting independent data may break source
-
NEW: AbortController signals in useAsyncData — Nuxt 4.2 adds signal parameter to handler for request cancellation control via useAsyncData('key', (_nuxtApp, { signal }) => $fetch(url, { signal })) source
-
NEW: appLayout in route rules — Nuxt 4.3 adds centralized layout management via routeRules: { '/admin/**': { appLayout: 'admin' } } source
-
NEW: ISR/SWR payload extraction — Nuxt 4.3 enables _payload.json generation for ISR/SWR routes, not just pre-rendered pages source
-
NEW: #server alias — Nuxt 4.3 provides clean #server/utils/helper imports within server directory, with import protection source
-
NEW: setPageLayout(name, props) — Nuxt 4.3 allows updating layout and passing props at runtime from middleware: setPageLayout('admin', { sidebar: true, theme: 'dark' }) source
-
NEW: Module disabling with false — Nuxt 4.3 allows disabling inherited modules: image: false in config source
-
NEW: route.meta.groups — Nuxt 4.3 exposes route groups (parenthesized folder names) in page meta for middleware authorization source
-
NEW: Vue Router v5 — Nuxt 4.4 upgrades to Vue Router v5, removing dependency on unplugin-vue-router source
-
NEW: refresh option for useCookie — Nuxt 4.4 adds refresh: true to extend cookie expiration without changing value source
-
NEW: clearNuxtState(key) resets to default — Nuxt 4.4 changes behavior to reset useState to initial value instead of undefined source
-
Use useFetch or useAsyncData for initial component data instead of $fetch — prevents double-fetching on SSR and ensures data reaches the client in the payload, avoiding hydration mismatches source
-
Always use useState in composables instead of module-level ref exports — module-level state persists across requests on the server, causing memory leaks and cross-user state pollution source
-
Wrap browser-only code in onMounted or use ClientOnly component — accessing browser APIs like localStorage or window at setup time causes hydration mismatches source
-
Use <NuxtLink> for internal navigation instead of <a> tags — automatically prefetches linked pages and intelligently switches between router links and plain anchors source
-
Enable lazy hydration with hydrate-on-visible or hydrate-on-idle for below-the-fold components — defers hydration until the component enters viewport or browser is idle, improving time-to-interactive source
-
Use the Lazy prefix for components to dynamically import them — splits code into chunks and delays loading until needed, reducing initial bundle size source
-
For asynchronous plugins, always set parallel: true — allows multiple async plugins to load concurrently instead of sequentially blocking rendering source
-
Never call Nuxt composables at module level (outside setup/plugins) — composables require access to the Nuxt context which is only available during component lifecycle or plugin execution source
-
Use useHeadSafe or useSeoMeta instead of useHead for user-generated content — restricts input to safe values and prevents XSS attacks source
-
Minimize plugin setup logic and defer expensive operations to hooks — plugins run during hydration phase; blocking operations degrade user experience and increase time-to-interactive source
-
Use <NuxtImg> instead of <img> tags for images — automatically optimises, resizes, converts to modern formats (WebP/Avif), and supports lazy loading for improved Core Web Vitals source
-
Define route rules for hybrid rendering to balance performance and freshness — use prerender, swr, isr, or ssr: false per route to optimise caching strategy without a single rendering mode source
-
Use $fetch only for event-based client interactions; use useFetch/useAsyncData for page data — $fetch lacks de-duplication and prevents Suspense, causing potential double-requests and hydration issues source
-
Avoid conditional rendering based on client-only values in setup — use CSS media queries or handle logic in onMounted instead to ensure identical server and client output source
