/nuxt-production

name: nuxt-production
description: "| Nuxt 4 production optimization: hydration, performance, testing with Vitest, deployment to Cloudflare/Vercel/Netlify, and v4 migration. 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 3 to Nuxt 4."
license: MIT
metadata:
  version: 4.0.0
  author: Claude Skills Maintainers
  category: Framework
  framework: Nuxt
  framework-version: 4.x
  last-verified: 2025-12-28
  keywords:
    - hydration
    - hydration mismatch
    - ClientOnly
    - SSR
    - performance
    - lazy loading
    - lazy hydration
    - Vitest
    - testing
    - deployment
    - Cloudflare Pages
    - Cloudflare Workers
    - Vercel
    - Netlify
    - NuxtHub
    - migration
    - Nuxt 3 to Nuxt 4

Nuxt 4 Production Guide

Hydration, performance, testing, deployment, and migration patterns.

What's New in Nuxt 4

v4.2 Features (Latest)

**1. Abort Control for Data Fetching**

const controller = ref<AbortController>()

const { data } = await useAsyncData(
  'users',
  () => $fetch('/api/users', { signal: controller.value?.signal })
)

const abortRequest = () => {
  controller.value?.abort()
  controller.value = new AbortController()
}

**2. Async Data Handler Extraction**

• 39% smaller client bundles
• Data fetching logic extracted to server chunks
• Automatic optimization (no config needed)

**3. Enhanced Error Handling**

• Dual error display: custom error page + technical overlay
• Better error messages in development

v4.1 Features

**1. Enhanced Chunk Stability**

• Import maps prevent cascading hash changes
• Better long-term caching

**2. Lazy Hydration**

<script setup>
const LazyComponent = defineLazyHydrationComponent(() =>
  import('./HeavyComponent.vue')
)
</script>

Breaking Changes from v3

| Change | v3 | v4 | |--------|----|----| | Source directory | Root | `app/` | | Data reactivity | Deep | Shallow (default) | | Default values | `null` | `undefined` | | Route middleware | Client | Server | | App manifest | Opt-in | Default |

When to Load References

**Load `references/hydration.md` when:**

• Debugging "Hydration node mismatch" errors
• Implementing ClientOnly components
• Fixing non-deterministic rendering issues
• Understanding SSR vs client rendering

**Load `references/performance.md` when:**

• Optimizing Core Web Vitals scores
• Implementing lazy loading and code splitting
• Configuring caching strategies
• Reducing bundle size

**Load `references/testing-vitest.md` when:**

• Writing component tests with @nuxt/test-utils
• Testing composables with Nuxt context
• Mocking Nuxt APIs (useFetch, useRoute)
• Setting up Vitest configuration

**Load `references/deployment-cloudflare.md` when:**

• Deploying to Cloudflare Pages or Workers
• Configuring wrangler.toml
• Setting up NuxtHub integration
• Working with D1, KV, R2 bindings

Hydration Best Practices

What Causes Hydration Mismatches

| Cause | Example | Fix | |-------|---------|-----| | Non-deterministic values | `Math.random()` | Use `useState` | | Browser APIs on server | `window.innerWidth` | Use `onMounted` | | Date/time on server | `new Date()` | Use `useState` or `ClientOnly` | | Third-party scripts | Analytics | Use `ClientOnly` |

Fix Patterns

**Non-deterministic Values:**

<!-- WRONG -->
<script setup>
const id = Math.random()
</script>

<!-- CORRECT -->
<script setup>
const id = useState('random-id', () => Math.random())
</script>

**Browser APIs:**

<!-- WRONG -->
<script setup>
const width = window.innerWidth  // Crashes on server!
</script>

<!-- CORRECT -->
<script setup>
const width = ref(0)
onMounted(() => {
  width.value = window.innerWidth
})
</script>

**ClientOnly Component:**

<template>
  <!-- Wrap client-only content -->
  <ClientOnly>
    <MyMapComponent />
    <template #fallback>
      <div class="skeleton">Loading map...</div>
    </template>
  </ClientOnly>
</template>

**Conditional Rendering:**

<script setup>
const showWidget = ref(false)

onMounted(() => {
  // Only show after hydration
  showWidget.value = true
})
</script>

<template>
  <AnalyticsWidget v-if="showWidget" />
</template>

Performance Optimization

Lazy Loading Components

<script setup>
// Lazy load heavy components
const HeavyChart = defineAsyncComponent(() =>
  import('~/components/HeavyChart.vue')
)

// With loading/error states
const HeavyChart = defineAsyncComponent({
  loader: () => import('~/components/HeavyChart.vue'),
  loadingComponent: LoadingSpinner,
  errorComponent: ErrorFallback,
  delay: 200,
  timeout: 10000
})
</script>

<template>
  <Suspense>
    <HeavyChart :data="chartData" />
    <template #fallback>
      <LoadingSpinner />
    </template>
  </Suspense>
</template>

Lazy Hydration

<script setup>
// Hydrate when visible in viewport
const LazyComponent = defineLazyHydrationComponent(
  () => import('./HeavyComponent.vue'),
  { hydrate: 'visible' }
)

// Hydrate on user interaction
const InteractiveComponent = defineLazyHydrationComponent(
  () => import('./InteractiveComponent.vue'),
  { hydrate: 'interaction' }
)

// Hydrate when browser is idle
const IdleComponent = defineLazyHydrationComponent(
  () => import('./IdleComponent.vue'),
  { hydrate: 'idle' }
)
</script>

Route Caching

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    // Static pages (prerendered at build)
    '/': { prerender: true },
    '/about': { prerender: true },

    // SWR caching (1 hour)
    '/blog/**': { swr: 3600 },

    // ISR (regenerate every hour)
    '/products/**': { isr: 3600 },

    // SPA mode (no SSR)
    '/dashboard/**': { ssr: false },

    // Static with CDN caching
    '/static/**': {
      headers: { 'Cache-Control': 'public, max-age=31536000' }
    }
  }
})

Image Optimizat