secondsky/claude-skills / plugins/nuxt-v5/skills/nuxt-production
nuxt-production
Verified| Nuxt 5 production optimization: hydration, performance, testing with Vitest, deployment to Cloudflare/Vercel/Netlify, and migration from Nuxt 4. Use when: debugging hydration mismatches, optimizing performance and Core Web Vitals, writing tests with Vitest, deploying to Cloudflare Pages/Workers/Vercel/Netlify, or migrating from Nuxt 4 to Nuxt 5.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.7 KB |
| references/deployment-cloudflare.md | markdown | 13.5 KB |
| references/hydration.md | markdown | 8.4 KB |
| references/performance.md | markdown | 11.8 KB |
| references/testing-vitest.md | markdown | 13.2 KB |
| templates/tests/components/BlogPost.test.ts | script | 1.2 KB |
| templates/wrangler.toml | config | 1.0 KB |
references/performance.md
View on GitHub# Performance Optimization
Comprehensive guide to optimizing Nuxt 5 applications for maximum performance.
## Table of Contents
- [Built-in Optimizations](#built-in-optimizations)
- [Component Optimization](#component-optimization)
- [Image Optimization](#image-optimization)
- [Font Optimization](#font-optimization)
- [Code Splitting](#code-splitting)
- [Caching Strategies](#caching-strategies)
- [Bundle Analysis](#bundle-analysis)
- [Prefetching & Preloading](#prefetching--preloading)
- [Database Optimization](#database-optimization)
- [Vite Optimizations](#vite-optimizations)
- [Nitro Optimizations](#nitro-optimizations)
- [Performance Monitoring](#performance-monitoring)
- [Best Practices Checklist](#best-practices-checklist)
- [Common Pitfalls](#common-pitfalls)
## Built-in Optimizations
Nuxt 5 includes many performance optimizations out of the box:
- **Automatic code splitting** by route
- **Tree shaking** to remove unused code
- **Minification** of JavaScript and CSS
- **Preloading** of critical resources
- **Prefetching** of linked pages
- **Async data handler extraction** (39% smaller bundles in v4.2)
- **Import maps** for better chunk stability (v4.1)
## Component Optimization
### Lazy Loading Components
```vue
<script setup>
// Lazy load heavy components
const HeavyChart = defineAsyncComponent(() =>
import('~/components/HeavyChart.vue')
)
const InteractiveMap = defineAsyncComponent(() =>
import('~/components/InteractiveMap.vue')
)
</script>
<template>
<div>
<!-- Only loads when rendered -->
<HeavyChart v-if="showChart" />
<!-- With loading state -->
<Suspense>
<InteractiveMap />
<template #fallback>
<div>Loading map...</div>
</template>
</Suspense>
</div>
</template>
```
### Lazy Hydration
```vue
<template>
<div>
<!-- Hydrate when visible -->
<HeavyComponent lazy-hydrate="visible" />
<!-- Hydrate on interaction -->
<InteractiveWidget lazy-hydrate="interaction" />
<!-- Hydrate after idle -->
<LowPriorityComponent lazy-hydrate="idle" />
<!-- Hydrate after delay -->
<DelayedComponent lazy-hydrate="delay:5000" />
</div>
</template>
```
### Lazy Hydration Without Auto-Imports (v4.1)
```vue
<script setup>
const LazyComponent = defineLazyHydrationComponent(() =>
import('./HeavyComponent.vue')
)
</script>
<template>
<LazyComponent />
</template>
```
### Lazy Prefix Convention
```text
components/
├── HeavyChart.vue # Auto-imported
├── LazyHeavyChart.vue # Lazy-loaded
├── InteractiveMap.vue # Auto-imported
└── LazyInteractiveMap.vue # Lazy-loaded
```
```vue
<template>
<div>
<!-- Auto-loaded -->
<HeavyChart />
<!-- Lazy-loaded (only when rendered) -->
<LazyHeavyChart v-if="showChart" />
</div>
</template>
```
## Image Optimization
### NuxtImg
```vue
<template>
<!-- Automatic optimization -->
<NuxtImg
src="/images/hero.jpg"
width="800"
height="600"
alt="Hero image"
loading="lazy"
format="webp"
quality="80"
/>
<!-- Responsive -->
<NuxtImg
src="/images/hero.jpg"
sizes="sm:100vw md:50vw lg:400px"
alt="Hero image"
/>
<!-- With provider (Cloudflare Images) -->
<NuxtImg
provider="cloudflare"
src="/images/hero.jpg"
width="800"
height="600"
/>
</template>
```
### NuxtPicture
```vue
<template>
<!-- Multiple formats (WebP, AVIF, fallback) -->
<NuxtPicture
src="/images/hero.jpg"
:img-attrs="{
alt: 'Hero image',
loading: 'lazy'
}"
sizes="sm:100vw md:50vw lg:400px"
/>
</template>
```
### Setup
```bash
npm install @nuxt/image
```
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@nuxt/image'],
image: {
// Cloudflare Images
cloudflare: {
baseURL: 'https://your-account.cloudflareimages.com'
},
// Or Cloudflare R2
providers: {
cloudflareR2: {
baseURL: 'https://your-bucket.r2.cloudflarestorage.com'
}
}
}
})
```
## Font Optimization
### @nuxt/fonts Module
```bash
npm install @nuxt/fonts
```
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@nuxt/fonts'],
fonts: {
families: [
{ name: 'Inter', provider: 'google' },
{ name: 'Roboto Mono', provider: 'google' }
],
// Automatic optimization
defaults: {
fallbacks: {
'sans-serif': ['Arial', 'sans-serif'],
'monospace': ['Courier New', 'monospace']
}
}
}
})
```
Features:
- **Automatic font subsetting**
- **Preloading** of critical fonts
- **Font display: swap** by default
- **Local font caching**
- **Self-hosted option**
## Code Splitting
### Route-Based Splitting
Automatic in Nuxt - each page is a separate chunk.
```text
pages/
├── index.vue → index-[hash].js
├── about.vue → about-[hash].js
└── blog/
├── index.vue → blog-index-[hash].js
└── [slug].vue → blog-slug-[hash].js
```
### Component-Based Splitting
```vue
<script setup>
// Separate chunk for this component
const HeavyComponent = defineAsyncComponent(() =>
import('~/components/HeavyComponent.vue')
)
</script>
```
### Manual Chunks
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
vite: {
build: {
rollupOptions: {
output: {
manualChunks: {
// Vendor chunk
vendor: ['vue', 'vue-router'],
// Heavy libraries
charts: ['chart.js'],
maps: ['leaflet']
}
}
}
}
}
})
```
## Caching Strategies
### Route Rules
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
routeRules: {
// Static pages (prerender)
'/': { prerender: true },
'/about': { prerender: true },
// ISR (Incremental Static Regeneration)
'/blog/**': {
swr: 3600, // Revalidate every hour
isr: true
},
// API caching
'/api/posts': {
swr: 600, // 10 minutes
cache: {
maxAge: 600
}
},
// SPA mode (no SSR)
'/dashboard/**': { ssr: false },
// Cache control headers
'/api/config': {
headers: {
'Cache-Control': 'public, max-age=3600, s-maxage=3600'
}
}
}
})
```
### API Response Caching
```typescript
// server/api/posts.get.ts
export default defineCachedEventHandler(
async (event) => {
const posts = await db.posts.findMany()
return posts
},
{
maxAge: 60 * 10, // 10 minutes
name: 'posts-list',
getKey: (event) => {
const query = getQuery(event)
return `posts-${query.page || 1}`
}
}
)
```
### Data Fetching Cache
```typescript
// Automatic caching with key
const { data } = await useFetch('/api/posts', {
key: 'posts-list',
// Cached for this session
})
// Force refresh
const { refresh } = await useFetch('/api/posts', {
key: 'posts-list'
})
await refresh() // Bypasses cache
```
## Bundle Analysis
### Analyze Bundle Size
```bash
# Build with analysis
npx nuxi analyze
# Opens bundle analyzer in browser
```
### Reduce Bundle Size
1. **Remove unused dependencies**
```bash
npm prune
```
2. **Use dynamic imports**
```typescript
// Instead of:
import HeavyLibrary from 'heavy-library'
// Use:
const HeavyLibrary = await import('heavy-library')
```
3. **Optimize imports**
```typescript
// Instead of:
import { Button, Input, Select } from '@nuxt/ui'
// Already optimized in Nuxt UI v4
```
4. **Enable tree shaking**
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
vite: {
build: {
terserOptions: {
compress: {
drop_console: true // Remove console.logs
}
}
}
}
})
```
## Prefetching & Preloading
### NuxtLink Prefetching
```vue
<template>
<!-- Prefetch on hover (default) -->
<NuxtLink to="/about">About</NuxtLink>
<!-- Prefetch on visibility -->
<NuxtLink to="/about" prefetch="visible">About</NuxtLink>
<!-- No prefetch -->
<NuxtLink to="/about" :prefetch="false">About</NuxtLink>
</template>
```
### Manual Prefetching
```typescript
const { prefetchComponents } = useNuxtApp()
// Prefetch components
await prefetchComponents('HeavyChart')
await prefetchComponents(['ComponentA', 'ComponentB'])
```
### Preload Critical Resources
```vue
<script setup>
useHead({
link: [
{
rel: 'preload',
as: 'font',
href: '/fonts/Inter-Regular.woff2',
type: 'font/woff2',
crossorigin: 'anonymous'
}
]
})
</script>
```
## Database Optimization
### Query Optimization
```typescript
// ❌ N+1 query problem
const users = await db.users.findMany()
for (const user of users) {
user.posts = await db.posts.findMany({
where: { userId: user.id }
})
}
// ✅ Single query with join
const users = await db.users.findMany({
include: {
posts: true
}
})
```
### Pagination
```typescript
// server/api/posts.get.ts
export default defineEventHandler(async (event) => {
const query = getQuery(event)
const page = Number(query.page) || 1
const limit = Number(query.limit) || 10
const [posts, total] = await Promise.all([
db.posts.findMany({
skip: (page - 1) * limit,
take: limit,
orderBy: { createdAt: 'desc' }
}),
db.posts.count()
])
return {
data: posts,
meta: {
page,
limit,
total,
totalPages: Math.ceil(total / limit)
}
}
})
```
### Connection Pooling
With Drizzle + D1, connection pooling is automatic.
## Vite Optimizations
### Pre-Bundling
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
vite: {
optimizeDeps: {
include: [
'chart.js',
'leaflet',
'marked'
]
}
}
})
```
### Chunk Size Warnings
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
vite: {
build: {
chunkSizeWarningLimit: 1000, // KB
rollupOptions: {
output: {
manualChunks: {
// Split large dependencies
}
}
}
}
}
})
```
## Nitro Optimizations
### Precomputed Dependencies (v4.2)
Automatic in Nuxt v4.2 - reduces cold start time.
### Compression
```typescript
// nuxt.config.ts
export default defineNuxtConfig({
nitro: {
compressPublicAssets: true, // Gzip/Brotli
minify: true
}
})
```
### Route Rules
```typescript
export default defineNuxtConfig({
nitro: {
routeRules: {
// Prerender static routes
'/': { prerender: true },
// Edge caching
'/api/**': { cache: { maxAge: 600 } }
}
}
})
```
## Performance Monitoring
### Web Vitals
```vue
<script setup>
import { useWebVitals } from '~/composables/useWebVitals'
const { lcp, fid, cls, ttfb } = useWebVitals()
// Send to analytics
watch([lcp, fid, cls, ttfb], (metrics) => {
console.log('Web Vitals:', metrics)
})
</script>
```
### Performance Marks
```typescript
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.hook('page:finish', () => {
performance.mark('page-rendered')
const measure = performance.measure(
'page-load',
'navigationStart',
'page-rendered'
)
console.log('Page load time:', measure.duration)
})
})
```
## Best Practices Checklist
- [ ] Use lazy loading for heavy components
- [ ] Enable lazy hydration where appropriate
- [ ] Optimize images with NuxtImg/NuxtPicture
- [ ] Use @nuxt/fonts for font optimization
- [ ] Implement route-based caching
- [ ] Cache API responses
- [ ] Analyze bundle size regularly
- [ ] Enable prefetching for linked pages
- [ ] Optimize database queries
- [ ] Use connection pooling
- [ ] Enable compression
- [ ] Monitor Web Vitals
- [ ] Prerender static pages
- [ ] Use ISR for dynamic content
## Common Pitfalls
❌ **Loading all components eagerly**
❌ **Not optimizing images**
❌ **Missing font optimization**
❌ **No API caching**
❌ **N+1 query problems**
❌ **Large bundle sizes**
❌ **No prefetching**
❌ **Missing compression**
❌ **Not monitoring performance**
---
**Last Updated**: 2025-11-09
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |