Nuxt

This skill covers Nuxt across all supported versions (3.x and 4.x), including:

• Nitro server engine: H3 event handlers, server routes, server middleware, deployment presets (15+ targets), routeRules for hybrid rendering
• Auto-imports: components, composables, utils, Vue core, Nuxt core -- scan directories, extend/disable
• File-based routing: dynamic params, catch-all, optional, route groups (v4), nested layouts, route middleware
• Data fetching: useFetch, useAsyncData, $fetch, SSR deduplication, pick/transform, lazy mode, parallel fetches
• Hybrid rendering: SSR, SSG (nuxi generate), ISR, SPA mode, per-route routeRules
• Modules ecosystem: @nuxt/image, @nuxt/content, @nuxt/ui, @pinia/nuxt, @nuxtjs/i18n, defineNuxtModule
• Runtime config: server-only vs public, environment variables, type safety
• TypeScript: strict mode, auto-generated types, separate tsconfig (v4)
• Nuxt DevTools: pages, components, imports, payload, runtime config, performance panels
• SSR: streaming, hydration, <ClientOnly>, useState for SSR-safe state
• Deployment: Node.js, Docker, Vercel, Netlify, Cloudflare, AWS Lambda, Deno, Bun

When a question is version-specific, read the matching file under references/versions/. When the version is unknown, give general guidance and note where behavior differs.

How to Approach Tasks

When you receive a request:

1. Classify the request type:

   • Troubleshooting -- Load references/diagnostics.md
   • Data Fetching -- Load references/patterns/data-fetching.md
   • Server Routes / API -- Load references/patterns/server-routes.md
   • Architecture / Design -- Load references/architecture.md
   • Deployment / Performance -- Load references/best-practices.md
   • Configuration -- Reference assets/nuxt.config.ts

2. Identify version -- Determine whether the user is on Nuxt 3.x or 4.x. Key differences: app/ directory structure, shared/ folder, shallowRef default, separate TypeScript configs. If unclear, ask.

3. Load context -- Read the relevant reference file for deep knowledge.

4. Analyze -- Apply Nuxt-specific reasoning. Consider SSR implications, auto-import behavior, Nitro server context, and hybrid rendering modes.

5. Recommend -- Provide actionable guidance with code examples. Prefer idiomatic Nuxt patterns (useFetch over raw $fetch in setup, useState over ref for SSR state).

6. Verify -- Suggest validation steps (Nuxt DevTools payload panel, nuxi prepare, build logs).

Core Expertise

Nitro Server Engine

Nitro compiles server code into a single deployable output with zero external runtime dependencies (.output/), portable across 15+ hosting targets. Every handler is an H3 event handler.

// server/api/hello.get.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event)
  const body = await readBody(event)
  return { message: `Hello ${query.name}` }
})

Server routes are auto-registered from server/api/ and server/routes/. HTTP method is inferred from filename suffix (.get.ts, .post.ts, .delete.ts).

Hybrid Rendering with routeRules

Mix SSR, SSG, ISR, and SPA per route:

routeRules: {
  '/':             { prerender: true },      // SSG at build time
  '/blog/**':      { isr: 60 },              // ISR every 60 seconds
  '/dashboard/**': { ssr: true },            // always SSR
  '/account/**':   { ssr: false },           // SPA (client-only)
  '/api/**':       { cors: true, headers: { 'cache-control': 's-maxage=60' } },
}

Auto-Imports

Nuxt scans specific directories and makes exports globally available:

Source	What is imported
components/	Vue SFCs as components
composables/	All named/default exports
utils/	All named/default exports
Nuxt core	useFetch, useState, useRoute, navigateTo, etc.
Vue core	ref, reactive, computed, watch, onMounted, etc.

Component naming: components/base/Button.vue becomes <BaseButton> (path flattened to PascalCase).

Data Fetching

Three options with different SSR behaviors:

	useFetch	useAsyncData	$fetch
SSR dedup	Yes	Yes	No
Reactive key	URL string (auto)	Explicit key arg	N/A
Best for	Simple URL fetches	Custom async logic	Mutations, event handlers

// useFetch -- simple, SSR-safe
const { data, status, error, refresh } = await useFetch('/api/users', {
  pick: ['id', 'name'],
  transform: (res) => res.users,
  watch: [currentPage],
})

// useAsyncData -- custom logic, explicit key
const { data: user } = await useAsyncData(
  'user-profile',
  () => $fetch(`/api/users/${userId.value}`),
  { watch: [userId] }
)

// $fetch -- event handlers and mutations only
async function submitForm() {
  await $fetch('/api/contact', { method: 'POST', body: formData.value })
}

File-Based Routing

pages/
  index.vue              -> /
  about.vue              -> /about
  blog/[slug].vue        -> /blog/:slug
  blog/[...path].vue     -> /blog/* (catch-all)
  [[...opt]].vue         -> optional catch-all

Route middleware:

// middleware/auth.ts
export default defineNuxtRouteMiddleware((to) => {
  const user = useSupabaseUser()
  if (!user.value) return navigateTo('/login')
})

Runtime Config

// nuxt.config.ts
runtimeConfig: {
  databaseUrl: process.env.DATABASE_URL,     // server-only
  jwtSecret: process.env.JWT_SECRET,
  public: {                                  // exposed to client
    apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api',
  }
}

// Usage in composable
const config = useRuntimeConfig()
config.databaseUrl        // server-only (throws on client)
config.public.apiBase     // available everywhere

Nuxt DevTools

Enable with devtools: { enabled: true }. Panels: Pages, Components, Imports, Payload, Runtime Config, Performance, Terminal. Component inspector overlay shows source file, props, and slots on hover.

Common Pitfalls

1. Double-fetch in SSR Using $fetch in onMounted fetches on server AND client. Always use useFetch/useAsyncData in <script setup> for SSR-safe data.

2. Using ref instead of useState for SSR state ref initializes independently on server and client. useState transfers state via SSR payload, preventing hydration mismatches.

3. Key collisions in useAsyncData Two calls with the same key share data (intentional for caching, bug if accidental). Use unique keys.

4. Pending forever with server: false + lazy: false lazy: false blocks SSR; server: false means no server fetch. Together they block indefinitely. Use lazy: true with server: false.

5. Body in GET requests readBody is for POST/PUT/PATCH. Use getQuery for GET parameters.

6. Hydration mismatches Date.now(), localStorage, window in <script setup> cause mismatches. Wrap in onMounted or if (import.meta.client).

7. Missing auto-imports Files must be in scanned directories (components/, composables/, utils/). Run nuxi prepare to regenerate .nuxt/types/.

8. Static definePageMeta definePageMeta is hoisted and statically analyzed at build time. Avoid dynamic values (computed refs, conditionals). Use useRoute() at runtime.

9. Stale data on re-navigation useFetch with a static key does not re-fetch by default. Add watch option or call refresh().

10. Deploying to wrong preset Nitro auto-detects some platforms. For explicit control, set nitro: { preset: 'cloudflare-pages' }.

Version-Specific Guidance

Version	Reference	What's version-specific
3	references/versions/3.md	Nuxt 3 features, compatibility version flag, migration to 4
4	references/versions/4.md	app/ directory, shared/ folder, separate TypeScript configs, shallowRef default, useId, useRouteAnnouncer

Reference Files

• references/architecture.md -- Nitro, auto-imports, routing, data fetching, modules, DevTools. Read for "how does X work" questions.
• references/best-practices.md -- Data fetching patterns, server routes, deployment strategies, module development. Read for design and quality questions.
• references/diagnostics.md -- Build errors, hydration mismatches, data fetching gotchas. Read when troubleshooting.

Configuration References

• assets/nuxt.config.ts -- Annotated Nuxt 4 configuration with all major options

Pattern Guides

• references/patterns/data-fetching.md -- useFetch vs useAsyncData vs $fetch decision tree, SSR patterns
• references/patterns/server-routes.md -- Nitro API routes with validation, auth, typed responses