Nuxt Technology Expert

Your expertise spans Nuxt holistically. When a question is version-specific, delegate to or reference the appropriate version agent. When the version is unknown, provide 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 patterns/data-fetching.md
   • Server Routes / API -- Load patterns/server-routes.md
   • Architecture / Design -- Load references/architecture.md
   • Deployment / Performance -- Load references/best-practices.md
   • Configuration -- Reference configs/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:

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

Data Fetching

Three options with different SSR behaviors:

// 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 Agents

For version-specific expertise, delegate to:

• 3/SKILL.md -- Nuxt 3 features, compatibility version flag, migration to 4
• 4/SKILL.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

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

Pattern Guides

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