Nuxt Skilld

Search

Use skilld search instead of grepping .skilld/ directories — hybrid semantic + keyword search across all indexed docs, issues, and releases. If skilld is unavailable, use npx -y skilld search.

skilld search "query" -p nuxt
skilld search "issues:error handling" -p nuxt
skilld search "releases:deprecated" -p nuxt

Filters: docs:, issues:, releases: prefix narrows by source type.

API Changes

This section documents version-specific API changes in Nuxt v4, prioritizing recent minor/major releases and breaking changes that affect runtime behavior.

Silent Breakage (v4.0 → v4.x)

• BREAKING: useAsyncData — v4 no longer reruns handler when data already exists from previous render. Old code that relied on auto-rerun will silently fail to refetch. Use refresh() explicitly or reactive keys instead. source

• BREAKING: public/ and assets/ aliases removed in v4. Old imports compile but resolve to undefined at runtime. Use relative paths or configure custom aliases in nuxt.config.ts. source

• BREAKING: TypeScript context separation — v4 creates separate tsconfig.app.json, tsconfig.server.json, and tsconfig.build.json projects. Code that imported between contexts (e.g., server code from app context) compiles in v3 but fails in v4 type checking. Requires refactoring to respect context boundaries. source

Breaking Changes (Explicit, v4.0 → v4.x)

• BREAKING: #app/components/layout → #app/components/nuxt-layout — import path changed in v4. Old imports fail at runtime. source

• BREAKING: Top-level generate option removed from nuxt.config.ts. Use route rules with prerender instead. source

• BREAKING: __NUXT__ global removed after hydration in v4. Code checking this property will error or behave unexpectedly. source

• BREAKING: Nuxt 2 support dropped in @nuxt/kit. Module authors using old kit APIs will fail in v4. Kit now requires Nuxt ≥3. source

Deprecations (Still work, but flagged for v5)

• DEPRECATED: createError({ statusCode, statusMessage }) → use status and statusText instead in v4.3+. Old properties work but are deprecated for Nitro v3/H3 v2 compatibility. source

New APIs (v4.1 → v4.3)

• NEW: setPageLayout(layout, props) — v4.3 added props parameter for dynamic layout configuration. source

• NEW: appLayout in route rules — v4.3 adds centralized layout control via routeRules: { '/admin/**': { appLayout: 'admin' } }. source

• NEW: #server alias — v4.3 provides clean imports within server directory: import { helper } from '#server/utils/helper'. source

• NEW: Route groups in page meta — v4.3 exposes route.meta.groups for pages in folder groups like (protected)/. source

• NEW: moduleDependencies — v4.1 allows modules to specify and configure dependencies with version constraints and setup overrides. source

• NEW: onInstall and onUpgrade hooks — v4.1 module lifecycle hooks triggered on first install and version upgrades. source

• NEW: getLayerDirectories() — v4.1 kit utility for accessing layer directories without private APIs. source

• NEW: useAsyncData with AbortController signal — v4.2 adds signal parameter to handler for request cancellation: useAsyncData('users', (_nuxtApp, { signal }) => $fetch(..., { signal })). source

• NEW: Error overlay in dev + custom error page — v4.2 displays both technical overlay and custom error page simultaneously during development. source

• NEW: Vite Environment API opt-in — v4.2 experimental viteEnvironmentApi: true flag for Vite 6 multi-environment support. source

Also changed: @nuxt/nitro-server extracted in v4.2 · extractAsyncDataHandlers experimental flag in v4.2 · typescriptPlugin experimental support in v4.2 · declarationPath for components in v4.2 · setGlobalHead() kit utility in v4.2 · resolveModule with extensions option in v4.2 · Import maps for chunk stability in v4.1 · Rolldown bundler support in v4.1 · defineLazyHydrationComponent without auto-imports in v4.1 · resolveFiles with ignore option in v4.1 · addServerImports single import support in v4.1 · ISR/SWR payload extraction in v4.3 · Draggable error overlay in v4.3 · Async plugin constructors in v4.3 · Disable modules via false in options in v4.3

Best Practices

• Use callOnce() to initialize global state server-side and avoid refetching on hydration — wraps SSR and client startup logic so it runs once instead of on every navigation, ideal for CMS data and config source

• Wrap useState() in factory composables (const useX = () => useState('x')) instead of declaring state at module scope — prevents cross-request state pollution on the server and memory leaks source

• Pass computed refs as useFetch() URLs for reactive data fetching — URL changes automatically trigger refetch and share cached data across components using the same key source

• Defer third-party library initialization to onMounted() hooks — prevents hydration mismatches caused by browser APIs or side effects in setup scope that don't exist server-side source

• Use useRequestFetch() for API calls on the server to automatically forward client headers and cookies — replaces the need for manual header propagation in SSR contexts source

• Replace localStorage with useCookie() for SSR-compatible persistent storage — cookies work on both server and client, avoiding hydration mismatches source

• Set parallel: true on async plugins to load concurrently — prevents sequential plugin blocking during app initialization and improves startup performance source

• Use createUseFetch() to build custom data-fetching composables with pre-configured baseURL and headers — fully typed and avoids repeating fetch options across the app source

• Use defineLazyHydrationComponent() with hydrate-on-visible or hydrate-on-interaction for below-fold components — defers hydration until needed (viewport visibility or user action) to reduce initial time-to-interactive source

• Configure hybrid rendering with routeRules to set caching per route — use prerender, swr (stale-while-revalidate), isr (incremental static regeneration), or ssr: false for fine-grained performance control without re-deploying source