---

name: nuxt3 description: | Nuxt 3 full-stack Vue framework. Covers file-based routing, data fetching, server routes, and auto-imports. Use when building Nuxt applications.

USE WHEN: user mentions "Nuxt", "Nuxt 3", asks about "useFetch", "Nuxt server routes", "Nitro", "Nuxt auto-imports", "Nuxt composables", "Nuxt middleware", "SSR with Vue"

DO NOT USE FOR: Vue without Nuxt - use frontend-vue instead; Next.js - use nextjs-app-router instead; Nuxt 2 - consult KB for migration; Astro - use astro instead allowed-tools: Read, Grep, Glob, Write, Edit

Nuxt 3 Core Knowledge

Full Reference: See advanced.md for WebSocket composable, Nitro WebSocket handlers, Socket.IO integration, plugin pattern, SSE, and room management patterns.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: nuxt for comprehensive documentation.

Directory Structure

Directory	Purpose
pages/	File-based routing
components/	Auto-imported components
composables/	Auto-imported composables
server/	Server routes & middleware
layouts/	Page layouts
middleware/	Route middleware

Page Component

<script setup lang="ts">
// Auto-imports work: ref, computed, useFetch, etc.
const { data, pending } = await useFetch('/api/users')

definePageMeta({
  layout: 'admin',
  middleware: 'auth'
})
</script>

<template>
  <div v-if="pending">Loading...</div>
  <div v-else>{{ data }}</div>
</template>

Data Fetching

Composable	Purpose
useFetch	SSR-friendly fetch with caching
useAsyncData	Custom async logic
$fetch	Direct fetch (no SSR handling)
useLazyFetch	Non-blocking fetch

Server Routes

// server/api/users.get.ts
export default defineEventHandler(async (event) => {
  const query = getQuery(event)
  return await db.users.findMany()
})

// server/api/users.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  return await db.users.create(body)
})

Key Features

• Auto-imports (components, composables, utils)
• Hybrid rendering (SSR, SSG, ISR, SPA)
• Nitro server engine
• Built-in state with useState

When NOT to Use This Skill

This skill is for Nuxt 3 (Vue meta-framework). DO NOT use for:

• Vue without Nuxt: Use frontend-vue skill instead
• Nuxt 2: Consult KB for migration to Nuxt 3
• Next.js (React meta-framework): Use nextjs-app-router skill instead
• Remix (React meta-framework): Use remix skill instead
• SvelteKit: Use sveltekit skill instead
• Astro: Use astro skill instead
• Vite-only setup: Use frontend-vue with Vite configuration

Anti-Patterns

Anti-Pattern	Why It's Wrong	Correct Approach
Using $fetch instead of useFetch	No SSR handling, data not cached	Use useFetch for SSR-friendly fetching
Fetching in onMounted	Client-side only, no SSR	Fetch in setup with useFetch/useAsyncData
Not using auto-imports	Unnecessary boilerplate	Rely on auto-imports for components/composables
Secrets in public runtimeConfig	Exposed to client, security risk	Use server-only runtimeConfig (not public)
Ignoring route rules	Missed performance opportunities	Set prerender, swr, or ssr rules per route
No error.vue	Poor error UX	Create error.vue for global error handling

Quick Troubleshooting

Issue	Possible Cause	Solution
"useFetch is not defined"	Auto-imports not working	Check .nuxt/tsconfig.json is generated, restart dev server
Data not available on SSR	Using $fetch instead of useFetch	Replace $fetch with useFetch
"useState is not defined"	Auto-import issue	Use useState composable (Nuxt 3), ensure .nuxt is built
API route 404 in production	Route not generated	Check server/api/ structure, rebuild
Hydration mismatch	Server/client render differently	Use , ensure consistent state
Components not auto-imported	Not in components/ directory	Move to components/ or configure in nuxt.config

Production Readiness

Security Configuration

// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    // Server-only (not exposed to client)
    dbPassword: process.env.DB_PASSWORD,

    // Exposed to client via useRuntimeConfig()
    public: {
      apiBase: process.env.API_BASE,
    },
  },
});

Error Handling

<!-- error.vue -->
<script setup lang="ts">
import type { NuxtError } from '#app';

const props = defineProps<{ error: NuxtError }>();
const handleError = () => clearError({ redirect: '/' });
</script>

<template>
  <div class="error-page">
    <h1>{{ error.statusCode }}</h1>
    <p>{{ error.message }}</p>
    <button @click="handleError">Go Home</button>
  </div>
</template>

Performance

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
    '/blog/**': { swr: 3600 }, // Stale-while-revalidate
    '/admin/**': { ssr: false }, // Client-only
  },
});

API Security

// server/api/users.post.ts
export default defineEventHandler(async (event) => {
  // Validate input
  const body = await readValidatedBody(event, (body) => {
    return z.object({
      email: z.string().email(),
      name: z.string().min(2),
    }).parse(body);
  });

  // Auth check
  const session = await requireAuth(event);

  return await createUser(body);
});

Testing

import { mountSuspended } from '@nuxt/test-utils/runtime';
import IndexPage from '~/pages/index.vue';

describe('Index Page', () => {
  it('renders correctly', async () => {
    const component = await mountSuspended(IndexPage);
    expect(component.text()).toContain('Welcome');
  });
});

Monitoring Metrics

Metric	Target
Time to First Byte	< 200ms
First Contentful Paint	< 1.5s
Hydration time	< 500ms
API response time	< 100ms

Checklist

• Security headers configured
• Runtime config for secrets
• Error handling (error.vue, plugins)
• Route rules (prerender, swr, ssr)
• Image optimization
• Lazy loaded components
• API validation (Zod)
• Rate limiting on API routes
• Auth middleware for protected routes
• E2E tests with @nuxt/test-utils

Reference Documentation

• Directory Structure
• Data Fetching Patterns