From nuxt-v5
Optimizes Nuxt 5 production: fixes hydration mismatches with ClientOnly comments, improves performance and Core Web Vitals, adds Vitest testing, deploys to Cloudflare/Vercel/Netlify, migrates from Nuxt 4.
npx claudepluginhub secondsky/claude-skills --plugin nuxt-v5This skill uses the workspace's default tool permissions.
Hydration, performance, testing, deployment, and migration patterns.
Generates design tokens/docs from CSS/Tailwind/styled-components codebases, audits visual consistency across 10 dimensions, detects AI slop in UI.
Records polished WebM UI demo videos of web apps using Playwright with cursor overlay, natural pacing, and three-phase scripting. Activates for demo, walkthrough, screen recording, or tutorial requests.
Delivers idiomatic Kotlin patterns for null safety, immutability, sealed classes, coroutines, Flows, extensions, DSL builders, and Gradle DSL. Use when writing, reviewing, refactoring, or designing Kotlin code.
Hydration, performance, testing, deployment, and migration patterns.
| 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 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>
To revert to the old <div> behavior:
// nuxt.config.ts
export default defineNuxtConfig({
experimental: {
clientNodePlaceholder: false
}
})
callHook may now return void instead of always returning Promise. Always use await:
// WRONG
nuxtApp.callHook('my:hook', data).then(() => { ... })
// CORRECT
await nuxtApp.callHook('my:hook', data)
Load references/hydration.md when:
Load references/performance.md when:
Load references/testing-vitest.md when:
Load references/deployment-cloudflare.md when:
| 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: 'john@example.com' }
}
})
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())
Hydration Mismatch:
window, document, localStorage usageClientOnly or use onMountedMath.random(), Date.now()<div> placeholder for client-only componentsBuild Errors:
rm -rf .nuxt .output node_modules/.vite && bun install
Vite Plugin Warnings:
extendViteConfig({ server }) to configEnvironmentapplyToEnvironment instead of server: false / client: falseRolldown Build Issues:
rollupOptions with rolldownOptionsvite.esbuild with vite.oxcVersion: 5.0.0 | Last Updated: 2026-03-30 | License: MIT