Comprehensive performance optimization guide for Nuxt 3/4 applications. Contains 40+ rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
When to Apply
Reference these guidelines when:
-
Writing new Nuxt pages, components, or composables
-
Implementing data fetching (useFetch, useAsyncData)
-
Creating server routes and API endpoints
-
Organizing types, composables, and auto-imports
-
Working with Nuxt modules and plugins
-
Configuring rendering modes (SSR, SSG, SPA)
Rule Categories by Priority
| 1
| Data Fetching
| CRITICAL
| data-
| 2
| Auto-Imports & Organization
| CRITICAL
| imports-
| 3
| Server & API Routes
| HIGH
| server-
| 4
| Rendering Modes
| HIGH
| rendering-
| 5
| State Management
| MEDIUM-HIGH
| state-
| 6
| Type Safety
| MEDIUM
| types-
| 7
| Modules & Plugins
| LOW-MEDIUM
| modules-
| 8
| Performance & Deployment
| LOW
| perf-
Quick Reference
1. Data Fetching (CRITICAL)
-
data-use-fetch- Use useFetch/useAsyncData, never raw fetch in components -
data-key-unique- Always provide unique keys for data fetching -
data-lazy-loading- Use lazy option for non-critical data -
data-transform- Transform data at fetch time, not in template -
data-error-handling- Always handle error and pending states -
data-refresh-patterns- Use refresh() and clear() appropriately
2. Auto-Imports & Organization (CRITICAL)
-
imports-no-barrel-autoimport- Never create barrel exports in auto-imported directories -
imports-component-naming- Don't duplicate folder prefix in component names -
imports-type-locations- Place types in dedicated directories (app/types, shared/types, server/types) -
imports-composable-exports- Composables export functions only, not types -
imports-direct-composable-imports- Use direct imports between composables
3. Server & API Routes (HIGH)
-
server-validated-input- Use getValidatedQuery/readValidatedBody with Zod -
server-route-meta- Always add defineRouteMeta for OpenAPI docs -
server-runtime-config- Use useRuntimeConfig, never process.env -
server-error-handling- Use createError for consistent error responses -
server-middleware-order- Understand middleware execution order
4. Rendering Modes (HIGH)
-
rendering-route-rules- Configure rendering per-route with routeRules -
rendering-hybrid- Use hybrid rendering for optimal performance -
rendering-prerender- Prerender static pages at build time -
rendering-client-only- Use ClientOnly for browser-specific components
5. State Management (MEDIUM-HIGH)
-
state-use-state- Use useState for SSR-safe shared state -
state-pinia-setup- Set up Pinia correctly with Nuxt -
state-hydration- Handle hydration mismatches properly -
state-computed-over-watch- Prefer computed over watch for derived state
6. Type Safety (MEDIUM)
-
types-no-inline- Never define types inline in components/composables -
types-import-paths- Use correct import paths (#shared, ~/, ~~/) -
types-no-any- Never useanytype -
types-zod-schemas- Use Zod for runtime validation with type inference -
types-strict-emits- Use kebab-case emits with full type definitions
7. Modules & Plugins (LOW-MEDIUM)
-
modules-order- Module order matters in nuxt.config -
modules-runtime-vs-build- Understand runtime vs build-time modules -
plugins-client-server- Use .client.ts and .server.ts suffixes correctly -
plugins-provide-inject- Use provide/inject for cross-cutting concerns
8. Performance & Deployment (LOW)
-
perf-bundle-analysis- Analyze and optimize bundle size -
perf-image-optimization- Use nuxt/image for optimized images -
perf-font-loading- Configure font loading strategy -
perf-caching-headers- Set appropriate cache headers
How to Use
Read individual rule files for detailed explanations and code examples:
rules/data-use-fetch.md
rules/imports-no-barrel-autoimport.md
rules/_sections.md
Each rule file contains:
-
Brief explanation of why it matters
-
Incorrect code example with explanation
-
Correct code example with explanation
-
Additional context and Nuxt-specific notes
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md