# Nuxt Knowledge Patch > Nuxt - Skill: `nevaberry/nuxt-knowledge-patch` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add nevaberry/nuxt-knowledge-patch` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/nuxt-knowledge-patch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/nuxt-knowledge-patch --- # Nuxt Knowledge Patch Use this skill when choosing current Nuxt APIs, defaults, migration paths, or ecosystem patterns. Read the topic reference that matches the task before changing code: behavior can differ by compatibility mode, builder, deployment preset, Nitro channel, or module major. ## Reference index | Reference | Topics | | --- | --- | | [upgrading.md](references/upgrading.md) | Major migrations, release channels, compatibility settings, removed options, dependency changes, and upgrade commands | | [data-fetching-and-state.md](references/data-fetching-and-state.md) | `useAsyncData`, `useFetch`, payloads, caching, preview mode, cookies, `callOnce`, and state reset behavior | | [routing-and-navigation.md](references/routing-and-navigation.md) | Pages, route rules, middleware, layouts, links, transitions, scrolling, and announcements | | [rendering-and-components.md](references/rendering-and-components.md) | Hydration, server components, islands, head APIs, built-ins, errors, and runtime hooks | | [modules-and-layers.md](references/modules-and-layers.md) | Nuxt Kit, module dependencies, layers, aliases, templates, imports, and build-time configuration | | [build-and-types.md](references/build-and-types.md) | Builders, TypeScript projects, source maps, debugging, profiling, HMR, CSS, and client bundles | | [nitro-and-deployment.md](references/nitro-and-deployment.md) | Nitro runtime, beta migration, routing, assets, caching, security, tasks, and deployment presets | | [ecosystem-modules.md](references/ecosystem-modules.md) | Nuxt Scripts, Icon, Content, UI, and Image package majors | ## Start with the compatibility boundary 1. Inspect `package.json`, the lockfile, `nuxt.config`, and generated type configuration. 2. Identify the Nuxt major, compatibility version, builder, Nitro major, and relevant ecosystem-module majors independently. 3. Keep Nuxt 3 applications on the v3 release channel when upgrading, using the deduplicating upgrade command. 4. Treat compatibility version 5 as an experimental preview, not a bounded migration target. 5. Treat Nitro 3 as an explicitly pinned beta unless the project already opts into it; do not infer Nitro's major from Nuxt's major. 6. Re-run type checking after changing source layout, compatibility defaults, modules, builders, or generated aliases. ## Breaking changes and deprecations ### Source layout and context boundaries - Expect application code under `app/` in new Nuxt 4 projects; keep `server/`, `shared/`, `content/`, `public/`, and configuration at the project root. - Preserve a detected Nuxt 3 layout unless the task explicitly includes a migration. - Respect separate application, server, shared, and builder TypeScript projects. Do not import `#server` from client or shared code. - Keep `shared/` context-independent and use `#shared` for explicit imports. - Account for path-prefixed component names under v4 defaults, especially in name-based `` filters. ### Removed and changed APIs - Remove obsolete experimental configuration rather than retaining inert flags. - Import `mergeModels` explicitly; it is no longer auto-imported. - Prefer `status` and `statusText` over deprecated `statusCode` and `statusMessage` in new error code. - Import head composables from Nuxt auto-imports or `#app/composables/head`, not directly from `@unhead/vue`, to preserve async context. - Augment Vue through `vue`; bridge legacy `@vue/runtime-core` augmentation only as a temporary compatibility measure. - Replace deprecated Vite extension hooks in module and builder integrations. - Check ESM-only dependency majors before relying on transitive Nuxt packages from CommonJS module code. ### Nitro beta migration - Pin the intended beta explicitly before adopting Nitro 3 behavior. - Expect production dependencies to be bundled by default; trace only native or incompatible exceptions. - Remove `nodeModulesDirs`, `nitro/deps/*`, custom `moduleSideEffects`, and the temporary TypeScript-paths option. - Import configuration, runtime, and HTTP utilities from the root `nitro` package; import `ServerRequest` from `nitro/types`. - Opt into filesystem routing with `serverDir`, and configure routes, renderer behavior, entries, and builders explicitly where needed. - Review Cloudflare binding access and bundling defaults before deployment. - Upgrade past the proxy and redirect security fixes when those route rules are in use. ### Ecosystem package majors - Define Content collections in `content.config.ts`; migrate queries to collection utilities and replace removed document-driven and `ContentSlot` APIs. - Define Image custom providers with a default-exported `defineProvider`; remove retired providers and update operation formatting. - Account for UI's Reka UI and Tailwind CSS integration before applying old Headless UI or styling assumptions. - Use the unified UI package for components that were previously separate Pro offerings. ## Data fetching and state ### Key identity and shared state - Give each explicit async-data key one stable meaning. - Expect callers with the same key to share refs, refreshes, cached-data lookup, and in-flight work. - Use reactive keys when data identity follows a ref, computed ref, or getter; expect old data to remain while a changed key loads. - Keep handlers side-effect-safe because prerendering, payload reuse, preview mode, refresh, and deduplication can change when they run. - Narrow absent data as `undefined`, not `null`. ### Cancellation and cache lifetime - Accept the handler abort signal and pass it to downstream requests. - Pass a caller-owned signal to `refresh()` or `execute()` when the caller controls cancellation. - Expect `clear()` and cancel-deduplicated refreshes to abort pending work. - Expect cached data to be purged after its consumers unmount unless legacy compatibility is explicitly retained. - Use payload extraction for cacheable routes when client navigation should consume `_payload.json` instead of refetching. - Enable client-mode payload extraction only after evaluating its opt-in compatibility behavior. ### State helpers - Expect a failed `callOnce` callback to be retryable; use navigation mode for once-per-navigation work. - Expect `clearNuxtState` to restore the initializer value. - Set `useCookie({ refresh: true })` when assigning the same value should renew expiration. - Disable Cookie Store synchronization explicitly when the browser integration is unwanted. ## Routing and rendering ### Pages, middleware, and layouts - Use parenthesized directories for pathless route groups and inspect `route.meta.groups` in middleware. - Attach named page middleware and layouts through `routeRules` when behavior applies to a route family. - Use a layout object in page metadata for type-checked props; pass runtime props as the second argument to `setPageLayout`. - Render `` when router integration is enabled; a bare `` is not a supported replacement. - Keep one `definePageMeta` call per file. ### Navigation behavior - Configure `NuxtLink` prefetch triggers for visibility, interaction, or both. - Use per-link trailing-slash formatting and object route locations through either `to` or `href` as appropriate. - Rely on navigation APIs to reject script-capable protocols and unsafe open redirects; do not bypass their checks. - Include `` in a custom `app.vue` and mount `` for non-navigation status messages. - Apply smooth-scroll configuration to hash scrolling and preserve focus behavior after hash navigation. ### Hydration and islands - Choose lazy hydration by visibility, idle time, interaction, media query, or delay; use `defineLazyHydrationComponent` for explicit imports. - Use `onPrehydrate` only for browser work immediately before hydration. - Treat server-island props as URL data: keep them non-secret, serializable, object-shaped, and small. - Verify whether a server component is present during prerender or first appears after client navigation before promising static-host support. - Current island links navigate client-side; do not retain an obsolete wrapper whose only job was preventing full-page navigation. ## Modules, layers, and builds ### Modules and layers - Let Nuxt auto-register local `layers/` and `modules/` directories. - Resolve layer paths with `getLayerDirectories`; use named `#layers/` aliases in imports and stylesheets. - Apply precedence deliberately: project files override layers, local layers use reverse alphabetical priority, and earlier `extends` entries override later ones. - Authenticate private remote layers through per-layer options and pin their branch or tag. - Declare module dependencies and compatibility in metadata; use async dependency calculation only when necessary. - Use install and upgrade hooks for lifecycle-specific module work. - Use `addServerTemplate`, Nitro type templates, server imports, and async builder-plugin factories instead of private internals. - Expect `.env` loading before schema resolution. ### Build and diagnostics - Verify plugins against the selected Vite, webpack, Rspack, or Rolldown-backed builder rather than assuming Vite-only behavior. - Keep Node built-ins in client code as explicit `node:` imports; install globals only in a client plugin when a dependency truly requires them. - Expect hashed-only client chunk names unless readable names are configured intentionally. - Use selective debug categories for focused diagnostics and build profiling for timing, RSS, heap, and plugin costs. - Expect virtual files, page metadata, and server-file watch events to update through HMR. - Use generated source maps and the development error overlay before adding custom error instrumentation. - Recheck generated TypeScript defaults, module resolution, arbitrary extensions, and server indexed access after upgrades. ## Task routing | If the task involves... | Read first | | --- | --- | | An upgrade, warning, removed option, or compatibility flag | [upgrading.md](references/upgrading.md) | | A stale request, duplicate fetch, cache miss, or payload issue | [data-fetching-and-state.md](references/data-fetching-and-state.md) | | Page discovery, middleware, layouts, links, or navigation accessibility | [routing-and-navigation.md](references/routing-and-navigation.md) | | Hydration, islands, server components, head state, or built-ins | [rendering-and-components.md](references/rendering-and-components.md) | | A module, layer, auto-import, generated template, or hook | [modules-and-layers.md](references/modules-and-layers.md) | | Builder behavior, typing, source maps, HMR, CSS, or performance | [build-and-types.md](references/build-and-types.md) | | Server runtime, route handlers, deployment, caching, tasks, or Nitro | [nitro-and-deployment.md](references/nitro-and-deployment.md) | | Scripts, Content, UI, Icon, or Image | [ecosystem-modules.md](references/ecosystem-modules.md) | ## Verification 1. Run the project's formatter, type checker, and focused tests. 2. Regenerate Nuxt types after changing modules, layers, aliases, source layout, or TypeScript configuration. 3. Exercise initial SSR and client navigation for routing, payload, hydration, island, or head changes. 4. Exercise the actual deployment preset for Nitro, asset, cache, WebSocket, queue, or scheduled-task changes. 5. Reinspect generated output when changing builders, chunk naming, source maps, payload extraction, or dependency tracing.