nuxt-production

secondsky/claude-skillsDeveloper ToolsAudit failedSnapshot da23c1fc0003

Installs: 0

Summary

| 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.

SKILL.md

Nuxt 5 Production Guide

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

What's New in Nuxt 5

v5 Key Changes

Change	Nuxt 4	Nuxt 5
Bundler	Vite 6 (esbuild + Rollup)	Vite 8 (Rolldown)
Server engine	Nitro v2	Nitro v3 (h3 v2)
Server errors	`createError({statusCode})`	`HTTPError({status})`
Client-only placeholder	Empty `<div>`	HTML comment node
callHook	Always returns Promise	May return void
clearNuxtState	Sets to `undefined`	Resets to initial default
Page names	Auto-generated	Normalized to route names
JSX support	Included by default	Optional (on-demand)
externalVue	Configurable	Removed (always mocked)

Client-Only Comment Placeholders (v5)

Client-only components (.client.vue files and createClientOnly() wrappers) now render an HTML comment on the server instead of an empty <div>. This fixes scoped styles hydration issues.

<!-- If you relied on the placeholder <div> for layout -->
<ClientOnly>
  <MyComponent />
  <template #fallback>
    <div class="placeholder" style="min-height: 200px"></div>
  </template>
</ClientOnly>

// nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    clientNodePlaceholder: false
  }
})

// WRONG
nuxtApp.callHook('my:hook', data).then(() => { ... })

// CORRECT
await nuxtApp.callHook('my:hook', data)

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`

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

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

<!-- ClientOnly component -->
<template>
  <ClientOnly>
    <MyMapComponent />
    <template #fallback>
      <div class="skeleton">Loading map...</div>
    </template>
  </ClientOnly>
</template>

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

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

const InteractiveComponent = defineLazyHydrationComponent(
  'interaction',
  () => import('./InteractiveComponent.vue')
)

const IdleComponent = defineLazyHydrationComponent(
  'idle',
  () => import('./IdleComponent.vue')
)
</script>

export default defineNuxtConfig({
  routeRules: {
    '/': { prerender: true },
    '/about': { prerender: true },
    '/blog/**': { swr: 3600 },
    '/products/**': { isr: 3600 },
    '/dashboard/**': { ssr: false },
    '/static/**': {
      headers: { 'Cache-Control': 'public, max-age=31536000' }
    }
  }
})

<template>
  <NuxtImg
    src="/images/hero.jpg"
    alt="Hero image"
    width="800"
    height="400"
    loading="lazy"
    placeholder
    format="webp"
  />

  <NuxtPicture
    src="/images/product.jpg"
    alt="Product"
    sizes="sm:100vw md:50vw lg:400px"
    :modifiers="{ quality: 80 }"
  />
</template>

bun add -d @nuxt/test-utils vitest @vue/test-utils happy-dom

// vitest.config.ts
import { defineVitestConfig } from '@nuxt/test-utils/config'

export default defineVitestConfig({
  test: {
    environment: 'nuxt',
    environmentOptions: {
      nuxt: {
        domEnvironment: 'happy-dom'
      }
    }
  }
})

import { describe, it, expect } from 'vitest'
import { mountSuspended } from '@nuxt/test-utils/runtime'
import UserCard from '~/components/UserCard.vue'

describe('UserCard', () => {
  it('renders user name', async () => {
    const wrapper = await mountSuspended(UserCard, {
      props: {
        user: { id: 1, name: 'John Doe', email: '[email protected]' }
      }
    })

    expect(wrapper.text()).toContain('John Doe')
  })
})

import { mockNuxtImport } from '@nuxt/test-utils/runtime'

mockNuxtImport('useFetch', () => {
  return () => ({
    data: ref({ users: [{ id: 1, name: 'John' }] }),
    pending: ref(false),
    error: ref(null)
  })
})

bun run build
bunx wrangler pages deploy .output/public

export default defineNuxtConfig({
  nitro: { preset: 'cloudflare_pages' }
})

export default defineNuxtConfig({
  nitro: { preset: 'cloudflare_module' }
})

// Vercel
export default defineNuxtConfig({
  nitro: { preset: 'vercel' }
})

// Netlify
export default defineNuxtConfig({
  nitro: { preset: 'netlify' }
})

bun add @nuxthub/core

export default defineNuxtConfig({
  modules: ['@nuxthub/core'],
  hub: {
    database: true,
    kv: true,
    blob: true,
    cache: true
  }
})

{
  "devDependencies": {
    "nuxt": "^5.0.0"
  }
}

// nuxt.config.ts
export default defineNuxtConfig({
  future: {
    compatibilityVersion: 5
  }
})

// Before (Nuxt 4)
import { createError } from 'h3'
throw createError({ statusCode: 404, statusMessage: 'Not Found' })

// After (Nuxt 5)
import { HTTPError } from 'nitro/h3'
throw new HTTPError({ status: 404, statusText: 'Not Found' })

// Before (Nuxt 4)
const path = event.path
event.node.res.statusCode = 200
setResponseHeader(event, 'x-custom', 'value')
const config = useRuntimeConfig(event)

// After (Nuxt 5)
const path = event.url.pathname
event.res.status = 200
event.res.headers.set('x-custom', 'value')
const config = useRuntimeConfig()

// Before (Nuxt 4)
export default defineNuxtConfig({
  vite: {
    build: {
      rollupOptions: { ... }
    }
  }
})

// After (Nuxt 5) - use rolldownOptions
export default defineNuxtConfig({
  vite: {
    build: {
      rolldownOptions: { ... }
    }
  }
})

// Before
routeRules: {
  '/old': { redirect: { to: '/new', statusCode: 302 } }
}

// After
routeRules: {
  '/old': { redirect: { to: '/new', status: 302 } }
}

// Before
import { defineEventHandler, getQuery } from 'h3'

// After
import { defineEventHandler, getQuery } from 'nitro/h3'
// Or rely on auto-imports (no import needed)

// Remove these from nuxt.config.ts
export default defineNuxtConfig({
  experimental: {
    externalVue: false,  // REMOVED - delete this
    viteEnvironmentApi: true,  // REMOVED - always enabled
  }
})

# Only if your project uses .jsx/.tsx files
bun add -D @vitejs/plugin-vue-jsx

// Before
nuxtApp.callHook('my:hook', data).then(() => { ... })

// After
await nuxtApp.callHook('my:hook', data)

// WRONG
const width = window.innerWidth

// CORRECT
if (import.meta.client) {
  const width = window.innerWidth
}

// Or use onMounted
onMounted(() => {
  const width = window.innerWidth
})

// WRONG
const id = Math.random()
const time = Date.now()

// CORRECT
const id = useState('id', () => Math.random())
const time = useState('time', () => Date.now())

rm -rf .nuxt .output node_modules/.vite && bun install

nuxt-production

Summary

Nuxt 5 Production Guide

What's New in Nuxt 5

v5 Key Changes

Client-Only Comment Placeholders (v5)

Non-Async callHook (v5)

When to Load References

Hydration Best Practices

What Causes Hydration Mismatches

Fix Patterns

Performance Optimization

Lazy Loading Components

Lazy Hydration

Route Caching

Image Optimization

Testing with Vitest

Setup

Component Testing

Mocking Composables

Deployment

Cloudflare Pages (Recommended)

Cloudflare Workers

Vercel / Netlify

NuxtHub (Cloudflare All-in-One)

Migration from Nuxt 4

Step 1: Update package.json

Step 2: Enable Compatibility Mode

Step 3: Update Server Error Handling

Step 4: Update Server Event API

Step 5: Update Vite Config

Step 6: Update Route Rules

Step 7: Update Import Paths

Step 8: Remove Deprecated Options

Step 9: Install JSX Plugin (If Needed)

Step 10: Update callHook Usage

Common Anti-Patterns

Client-Only Code on Server

Non-Deterministic SSR

Troubleshooting

Related Skills

Related skills