Nuxt Cursor Rules: Vue Full-Stack Framework Guide

---
description: Enforces best practices for Nuxt development, focusing on SSR, auto-imports, composable patterns, and Vue 3 conventions. Provides comprehensive guidelines for writing clean, performant full-stack applications with proper context.
globs: **/*.{vue,js,ts}
---
# Nuxt Best Practices

You are an expert in Nuxt development and related web technologies.
You understand modern Nuxt development practices, architectural patterns, and the importance of providing complete context in code generation.

### Context-Aware Code Generation
- Provide complete page context including route params, composable data, and component hierarchy
- Include nuxt.config.ts and tsconfig.json when generating project code
- Generate complete async component signatures with proper types and documentation
- Document the SSR/CSR rendering path for each page

### Project Structure
- /pages - file-based routing with automatic code splitting
- /components - auto-imported Vue components (no manual import needed)
- /composables - auto-imported Vue composables prefixed with "use"
- /server - Nitro API routes and middleware for backend logic
- /assets - uncompiled assets processed by Vite (styles, images, fonts)

### SSR & Static Generation
- Enable SSR by default for SEO and initial page load performance
- Use prerender for static routes that don't need dynamic data
- Use useFetch with server option for data fetched during SSR
- Leverage <ClientOnly> for components that must render client-side
- Use navigateTo for programmatic client-side navigation

### Composable Patterns
- Use useFetch for data fetching with automatic caching and deduplication
- Use useState for shared reactive state across components
- Prefix all composables with "use" for auto-import convention
- Keep composables focused on a single concern (data fetching, auth, theme)
- Return reactive refs and functions from composables, not raw objects

### Auto-Imports & Modules
- Auto-imports work for components, composables, and utils without explicit import statements
- Use Nuxt modules for third-party integrations (auth, sitemap, SEO)
- Configure module options in nuxt.config.ts under the modules array
- Use Nuxt DevTools for debugging and performance profiling

### Security
- Validate and sanitize all server route inputs
- Use useFetch with proper headers for authenticated API calls
- Set security headers via nitropack or the nuxt-security module
- Sanitize user content rendered with v-html to prevent XSS

### Testing & Quality
- Write tests for composables and server routes with Vitest
- Test page rendering with @nuxt/test-utils and vue-test-utils
- Use TypeScript strict mode for type safety across the application
- Run nuxt build to catch compilation errors before deployment

### Build & Deployment
- Generate TypeScript by default for type safety
- Use Composition API with <script setup> for all components
- Include proper types for component props with defineProps
- Add error boundaries with NuxtErrorBoundary for async data failures
- Deploy to Node.js server, serverless, or static hosting based on rendering mode

<!-- pages/posts.vue — SSR page with proper data fetching pattern -->
<script setup lang="ts">
const { data: posts, pending, error } = await useFetch('/api/posts')

definePageMeta({
  title: 'Blog Posts',
})
</script>

<template>
  <div>
    <h1>Blog Posts</h1>
    <div v-if="pending">Loading...</div>
    <div v-else-if="error">Failed to load posts</div>
    <ul v-else>
      <li v-for="post in posts" :key="post.id">{{ post.title }}</li>
    </ul>
    <ClientOnly>
      <LikeButton :initial-count="0" />
    </ClientOnly>
  </div>
</template>

<!-- composables/useAuth.ts — Auto-imported, no manual import needed -->
<script setup lang="ts">
const { user, loading, login } = useAuth()
</script>

<template>
  <button :disabled="loading" @click="login('[email protected]', 'pw')">
    {{ loading ? 'Logging in...' : 'Login' }}
  </button>
</template>