菜单
This skill ensures AI agents write correct, modern Nuxt 4 code and avoid common mistakes from outdated Nuxt 3 patterns. Always read this before writing any Nuxt code.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | nuxt-4-skill |
| description | This skill ensures AI agents write correct, modern Nuxt 4 code and avoid common mistakes from outdated Nuxt 3 patterns. Always read this before writing any Nuxt code. |
Purpose: This skill ensures AI agents write correct, modern Nuxt 4 code and avoid common mistakes from outdated Nuxt 3 patterns. Always read this before writing any Nuxt code. Last verified: February 2025 | Nuxt 4.x stable (released July 2025)
Nuxt 4 was officially released in July 2025. It is a stability-focused major release that builds on Nuxt 3 with breaking changes in project structure, data fetching, TypeScript, and tooling. Nuxt 3 reaches end-of-maintenance in January 2026.
If you have training data from Nuxt 3, many patterns are now outdated. Always prefer the patterns documented in this skill.
| Area | Nuxt 3 (Old) | Nuxt 4 (Current) |
|---|---|---|
| Directory structure | Flat root (pages/, components/ at root) | app/ directory (source code lives in app/) |
| Data fetching reactivity | Deep reactive refs by default | shallowRef by default for better performance |
| Data fetching keys | Independent per call | Singleton: shared refs for same key |
| Route middleware | defineNuxtRouteMiddleware (some guides) | defineNuxtRouteMiddleware with async support |
<head> management | Unhead v1 | Unhead v2 (removed vmid, hid, children) |
| Component names | Vue default naming | Normalized to match Nuxt auto-import pattern |
| Module loading in layers | Project modules loaded first (incorrect) | Layer modules first, project modules last (correct) |
| Route metadata | Available on both route.name and route.meta.name | Only on route.name (deduplicated) |
| Page meta scanning | Before pages:extend hook | After pages:extend hook |
| Node.js requirement | 16+ | 18.20+ (LTS 20+ recommended) |
| Generate config | generate.exclude, generate.routes | Removed. Use nitro.prerender instead |
| Inline styles | All CSS inlined | Only Vue component CSS inlined; global CSS as separate file |
my-nuxt-app/
├── app/ # ← ALL application source code goes here
│ ├── assets/
│ ├── components/
│ ├── composables/
│ ├── layouts/
│ ├── middleware/ # Route middleware (client-side)
│ ├── pages/
│ ├── plugins/
│ ├── utils/
│ ├── app.vue
│ ├── app.config.ts
│ ├── error.vue
│ ├── router.options.ts
│ └── spa-loading-template.html
├── content/ # Nuxt Content (at root, NOT inside app/)
├── layers/ # Nuxt Layers (at root)
├── modules/ # Local modules (at root)
├── public/ # Static assets (at root)
├── shared/ # Shared code between app and server
├── server/ # Server code (at root, NOT inside app/)
│ ├── api/
│ ├── middleware/ # Server middleware (Nitro/h3)
│ ├── plugins/
│ ├── routes/
│ └── utils/
├── nuxt.config.ts
├── package.json
└── tsconfig.json
~ alias now points to app/ by default (your srcDir).~/components resolves to app/components/, ~/pages to app/pages/, etc.server/, content/, layers/, modules/, and public/ stay at the project root, NOT inside app/..git/ and node_modules/ from being scanned by file watchers.// nuxt.config.ts
export default defineNuxtConfig({
srcDir: '.',
dir: {
app: 'app',
},
})
| Method | Use Case |
|---|---|
useFetch | Simple data fetching in components (wrapper around useAsyncData + $fetch) |
useAsyncData | Complex async operations, custom fetch logic |
$fetch | Direct HTTP calls (event handlers, non-component code, client-only actions) |
// Nuxt 4: data is a shallowRef (NOT deeply reactive)
const { data } = await useFetch('/api/users')
// If you need deep reactivity (rare, impacts performance):
const { data } = await useFetch('/api/users', { deep: true })
Do NOT set deep: true globally unless absolutely necessary. ShallowRef provides massive performance improvements on nested data structures.
All calls to useAsyncData/useFetch with the same key now share the same data, error, and status refs.
// ✅ CORRECT: Same key = shared data across components
// Component A
const { data: product } = await useFetch(`/api/products/${id}`, {
key: `product-${id}`
})
// Component B (different file, same key)
const { data: product } = await useFetch(`/api/products/${id}`, {
key: `product-${id}`
})
// → No duplicate API call! Uses the same shared ref.
Important Rules:
deep, transform, pick, getCachedData, and default options.// app/composables/useProduct.ts
export function useProduct(productId: string) {
return useAsyncData(
`product-${productId}`,
() => $fetch(`/api/products/${productId}`),
{
deep: true,
transform: (product) => ({
...product,
formattedPrice: `${product.price.toFixed(2)} kr`,
}),
}
)
}
getCachedData Now Receives Context// Nuxt 4: getCachedData has a context parameter
useAsyncData('key', fetchFunction, {
getCachedData: (key, nuxtApp, ctx) => {
// ctx.cause can be: 'initial' | 'refresh:hook' | 'refresh:manual' | 'watch'
// Example: Always refetch on manual refresh
if (ctx.cause === 'refresh:manual') return undefined
return nuxtApp.payload.data[key] || nuxtApp.static.data[key]
}
})
// Nuxt 4: Keys can be reactive (computed, ref, getter)
const id = computed(() => route.params.id)
const { data: post } = await useFetch(() => `/api/posts/${id.value}`)
// → Automatically refetches when id changes
When the last component using a useAsyncData key unmounts, Nuxt automatically removes the cached data to prevent memory leaks.
// ❌ WRONG: Using $fetch in component setup (causes double fetch on SSR + hydration)
const data = ref(null)
data.value = await $fetch('/api/users')
// ✅ CORRECT: Use useFetch or useAsyncData in components
const { data } = await useFetch('/api/users')
// ❌ WRONG: Conflicting options with same key
const { data: a } = useAsyncData('users', () => $fetch('/api/users'), { deep: false })
const { data: b } = useAsyncData('users', () => $fetch('/api/users'), { deep: true })
// → Nuxt 4 will warn about this!
// ✅ CORRECT: Use $fetch in server routes and event handlers
// server/api/combined.get.ts
export default defineEventHandler(async () => {
const [users, posts] = await Promise.all([
$fetch('/api/users'),
$fetch('/api/posts'),
])
return { users, posts }
})
Server routes live in server/ at the project root (NOT inside app/).
server/
├── api/
│ ├── hello.ts → GET/POST/etc. /api/hello
│ ├── hello.get.ts → GET /api/hello
│ ├── hello.post.ts → POST /api/hello
│ ├── users/
│ │ ├── index.get.ts → GET /api/users
│ │ ├── index.post.ts → POST /api/users
│ │ └── [id].get.ts → GET /api/users/:id
├── routes/
│ └── health.ts → /health (no /api prefix)
├── middleware/
│ └── log.ts → Runs on every request
├── plugins/
│ └── startup.ts → Nitro server plugins
└── utils/
└── auth.ts → Auto-imported server utilities
// server/api/users.get.ts
export default defineEventHandler(async (event) => {
// Read query parameters
const query = getQuery(event)
// Return data (auto-serialized as JSON)
return { users: ['Alice', 'Bob'] }
})
// server/api/users.post.ts
export default defineEventHandler(async (event) => {
// Read and validate body
const body = await readValidatedBody(event, z.object({
name: z.string().min(1),
email: z.string().email(),
}).parse)
// Return created resource
return { user: body }
})
// server/api/users/[id].get.ts
export default defineEventHandler(async (event) => {
const id = getRouterParam(event, 'id')
// Or with validation:
// const { id } = await getValidatedRouterParams(event, z.object({ id: z.string() }).parse)
return { id, name: 'Alice' }
})
// ✅ CORRECT: Use createError to throw proper HTTP errors
export default defineEventHandler(async (event) => {
const user = await findUser(event)
if (!user) {
throw createError({
statusCode: 404,
message: 'User not found',
})
}
return user
})
// ❌ WRONG: Returning error objects (sends 200 with error body)
export default defineEventHandler(async (event) => {
const user = await findUser(event)
if (!user) {
return { code: 404, message: 'User not found' } // DON'T DO THIS
}
return user
})
Prefer server utils over global server middleware for route-specific logic:
// server/utils/auth.ts (Auto-imported)
export async function requireAuth(event: H3Event) {
const session = await getUserSession(event)
if (!session) {
throw createError({ statusCode: 401, message: 'Unauthorized' })
}
return session
}
// server/api/protected-data.get.ts
export default defineEventHandler(async (event) => {
const session = await requireAuth(event) // Explicit, clear
return { secret: 'data' }
})
Only use global server middleware for truly global concerns (logging, CORS headers):
// server/middleware/log.ts
export default defineEventHandler((event) => {
console.log('Request:', getRequestURL(event))
// Don't return anything — middleware should not respond
})
// server/api/admin/dashboard.get.ts
export default defineEventHandler({
onRequest: [
(event) => requireAuth(event),
(event) => requireRole(event, 'admin'),
],
handler: async (event) => {
return { dashboard: 'data' }
},
})
Route middleware lives in app/middleware/ and runs in the Vue/browser context (not server).
app/middleware/auth.ts → applied via definePageMetaapp/middleware/tracking.global.ts → runs on every route changedefinePageMeta// app/middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
const { isLoggedIn } = useAuth()
if (!isLoggedIn) {
return navigateTo('/login')
}
})
// Usage in a page:
// app/pages/dashboard.vue
definePageMeta({
middleware: ['auth'], // or middleware: 'auth'
})
// Nuxt 4 allows async middleware natively
export default defineNuxtRouteMiddleware(async (to, from) => {
const { data } = await useFetch('/api/auth/check')
if (!data.value?.authenticated) {
return navigateTo('/login')
}
})
undefined or nothing → continue navigationnavigateTo('/path') → redirect (302 on server)navigateTo('/path', { redirectCode: 301 }) → permanent redirectabortNavigation() → cancel navigationabortNavigation(error) → cancel with errornuxt.config.ts — Nuxt 4 Patterns// nuxt.config.ts
export default defineNuxtConfig({
// ✅ Nuxt 4 defaults — no compatibilityVersion needed
// Runtime config (with full IntelliSense in Nuxt 4)
runtimeConfig: {
apiSecret: '', // Server-only, set via NUXT_API_SECRET env var
public: {
apiBase: '', // Client + Server, set via NUXT_PUBLIC_API_BASE
},
},
// Modules
modules: [
'@nuxtjs/supabase',
'@nuxt/ui',
],
// ❌ REMOVED in Nuxt 4 — don't use:
// generate: { exclude: [...], routes: [...] }
// ✅ Use nitro.prerender instead:
nitro: {
prerender: {
ignore: ['/admin', '/private'],
routes: ['/sitemap.xml'],
},
},
// Route rules (SSR, caching, redirects)
routeRules: {
'/': { prerender: true },
'/api/**': { cache: { maxAge: 60 * 60 } },
'/old-page': { redirect: { to: '/new-page', statusCode: 302 } },
},
// Testing Nuxt 5 features early (optional)
// future: {
// compatibilityVersion: 5,
// },
})
<head> Management (Unhead v2)// ❌ Nuxt 3 / Unhead v1 — REMOVED in Nuxt 4
useHead({
meta: [{ name: 'description', content: '...', vmid: 'desc', hid: 'desc' }]
})
// ✅ Nuxt 4 / Unhead v2
useHead({
meta: [{ name: 'description', content: '...' }]
})
#imports Instead of @unhead/vue// ✅ Preferred in Nuxt 4
import { useHead, useSeoMeta } from '#imports'
// ❌ Still works but not recommended
import { useHead } from '@unhead/vue'
useSeoMeta — Preferred for SEO// app/pages/about.vue
useSeoMeta({
title: 'About Us',
description: 'Learn about our company.',
ogTitle: 'About Us',
ogDescription: 'Learn about our company.',
ogImage: '/images/og-about.png',
})
app/composables/ — auto-imported in app contextapp/utils/ — auto-imported in app contextserver/utils/ — auto-imported in server contextshared/ — shared between app and server (new in Nuxt 4)// app/composables/useCounter.ts
export function useCounter(initial = 0) {
const count = useState('counter', () => initial)
function increment() {
count.value++
}
return { count, increment }
}
// Usage — auto-imported, no import needed:
// app/pages/index.vue
const { count, increment } = useCounter()
useState for Shared State// ✅ Use useState for SSR-safe reactive state shared across components
const user = useState('user', () => null)
// ❌ DON'T use plain ref for shared state (causes hydration mismatches)
const user = ref(null)
Nuxt 4 generates a tsconfig.json with project references that separate:
app/ context (Vue, browser APIs, auto-imports)server/ context (h3, Nitro, Node APIs)shared/ context (code shared between both)This means:
app/ code (and vice versa)shared/ for types and functions needed in both contexts// Nuxt 4 infers API response types from server routes
const { data } = await useFetch('/api/users')
// data is typed based on the return type of server/api/users.ts
server/ Inside app/# WRONG
app/
server/ ← Server code must be at project root!
pages/
# CORRECT
app/
pages/
server/ ← At root level
generate Config// WRONG — removed in Nuxt 4
export default defineNuxtConfig({
generate: {
routes: ['/about', '/contact']
}
})
// CORRECT
export default defineNuxtConfig({
nitro: {
prerender: {
routes: ['/about', '/contact']
}
}
})
$fetch in Component Setup// WRONG — causes double fetching (SSR + client hydration)
const users = ref([])
users.value = await $fetch('/api/users')
// CORRECT — SSR-safe, transfers payload to client
const { data: users } = await useFetch('/api/users')
vmid or hid in useHead// WRONG — removed in Unhead v2
useHead({ meta: [{ name: 'desc', content: '...', hid: 'desc' }] })
// CORRECT
useHead({ meta: [{ name: 'description', content: '...' }] })
// WRONG — returns 200 with error body
return { statusCode: 404, message: 'Not found' }
// CORRECT — throws proper HTTP error
throw createError({ statusCode: 404, message: 'Not found' })
// WRONG (Nuxt 4) — metadata is no longer duplicated
const name = route.meta.name
// CORRECT
const name = route.name
// In Nuxt 4, data from useFetch is a shallowRef
const { data } = await useFetch('/api/nested-object')
// WRONG — mutating nested properties won't trigger reactivity
data.value.nested.property = 'new value'
// CORRECT — replace the entire value or use deep: true
data.value = { ...data.value, nested: { ...data.value.nested, property: 'new value' } }
// OR use deep: true (performance cost):
const { data } = await useFetch('/api/nested-object', { deep: true })
pages:extend to Override Page Meta// WRONG in Nuxt 4 — metadata scanning happens after pages:extend
hooks: {
'pages:extend'(pages) {
pages[0].meta.layout = 'custom' // May not work
}
}
// CORRECT — use pages:resolved
hooks: {
'pages:resolved'(pages) {
pages[0].meta.layout = 'custom'
}
}
When calling protected API routes during SSR, the cookie is not automatically forwarded:
// ❌ WRONG — cookie not forwarded during SSR
const { data } = await useFetch('/api/protected')
// ✅ CORRECT — forward cookies during SSR
const { data } = await useFetch('/api/protected', {
headers: useRequestHeaders(['cookie']),
})
For auth patterns, consider using nuxt-auth-utils which handles this automatically with useUserSession().
// nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
// Server-only (never exposed to client)
supabaseServiceKey: '', // → NUXT_SUPABASE_SERVICE_KEY
// Client + server
public: {
supabaseUrl: '', // → NUXT_PUBLIC_SUPABASE_URL
supabaseAnonKey: '', // → NUXT_PUBLIC_SUPABASE_ANON_KEY
},
},
})
// In app code (client or server)
const config = useRuntimeConfig()
config.public.supabaseUrl
// In server code only
const config = useRuntimeConfig()
config.supabaseServiceKey // Server-only key
npm install nuxt@^4.0.0npx codemod@0.18.7 nuxt/4/migration-recipeapp/ directoryserver/, content/, public/ at project rootgenerate config with nitro.prerendervmid/hid from useHead callsgetCachedData implementations (new context parameter)useAsyncData keys for conflicting optionsroute.meta.name to route.namepages:extend meta overrides to pages:resolved| Module | Purpose |
|---|---|
@nuxt/ui | UI component library (v4 for Nuxt 4) |
@nuxtjs/supabase | Supabase integration |
nuxt-auth-utils | Session/auth management |
@nuxt/content | Content management (v3 for Nuxt 4) |
@nuxtjs/tailwindcss | Tailwind CSS integration |
@nuxt/image | Image optimization |
@nuxt/eslint | ESLint configuration |
@pinia/nuxt | State management |
Always check module compatibility with Nuxt 4 before installing. Many popular modules have released Nuxt 4-compatible versions.
When writing Nuxt code:
app/ directory structure for new projects.$fetch in component <script setup> — use useFetch or useAsyncData.shallowRef is the default — don't assume deep reactivity on fetched data.createError() for server route errors, never return error objects.useRequestHeaders(['cookie']) when calling protected APIs during SSR.#imports instead of importing from @unhead/vue or other Nuxt-provided packages directly.defineEventHandler, useFetch, useHead, etc. unless needed for type clarity.shared/ directory for code that needs to run in both app and server contexts.