Nuxt App Speed: A Complete A-Z Optimization Guide

// Nuxt automatically splits into chunks:
// - pages/index.vue → _nuxt/index-[hash].js
// - pages/about.vue → _nuxt/about-[hash].js
// - components/Heavy.vue → _nuxt/Heavy-[hash].js (if lazy)

<template>
  <!-- Prefetch will trigger automatically on entering the viewport -->
  <NuxtLink to="/products">Catalog</NuxtLink>
  
  <!-- Disable prefetch for a specific link -->
  <NuxtLink to="/heavy-page" :prefetch="false">
    Heavy Page
  </NuxtLink>
</template>

// nuxt.config.ts
export default defineNuxtConfig({
  routeRules: {
    // Static homepage
    '/': { prerender: true },
    
    // Catalog: 1-hour cache, background refresh
    '/products/**': { swr: 3600 },
    
    // Blog: CDN cache with ISR
    '/blog/**': { isr: true },
    
    // Admin: client-side only
    '/admin/**': { ssr: false },
    
    // API: CORS + cache
    '/api/**': { 
      cors: true,
      cache: { maxAge: 60 }
    }
  }
})

<script setup>
const showModal = ref(false)
</script>

<template>
  <button @click="showModal = true">Open</button>
  
  <!-- The code will only be loaded when showModal = true -->
  <LazyModal v-if="showModal" @close="showModal = false" />
</template>

<template>
  <!-- Hydrate when it enters the viewport -->
  <LazyFooter hydrate-on-visible />
  
  <!-- Hydrate when the browser is idle -->
  <LazySidebar hydrate-on-idle />
  
  <!-- Hydrate on interaction -->
  <LazyComments hydrate-on-interaction="click" />
  
  <!-- Hydrate on a media query -->
  <LazyMobileMenu hydrate-on-media-query="(max-width: 768px)" />
  
  <!-- Never hydrate (purely static content) -->
  <LazyStaticBanner hydrate-never />
</template>

<!-- components/RenderMarkdown.server.vue -->
<script setup>
const props = defineProps<{ source: string }>()
</script>

<template>
  <div v-html="renderMarkdown(props.source)" />
</template>

<template>
  <NuxtIsland name="HeavyChart" :props="{ data }" />
</template>

npx nuxi module add @nuxt/image

<template>
  <!-- Instead of <img> -->
  <NuxtImg 
    src="/hero.jpg"
    width="1200"
    height="600"
    alt="Hero image"
    format="webp"
    loading="lazy"
  />
  
  <!-- For an LCP image -->
  <NuxtImg 
    src="/hero.jpg"
    width="1200"
    height="600"
    alt="Hero image"
    :loading="undefined"
    fetchpriority="high"
  />
</template>

<template>
  <!-- ❌ Bad: lazy for LCP -->
  <NuxtImg src="/hero.jpg" loading="lazy" />
  
  <!-- ✅ Good: eager + fetchpriority for LCP -->
  <NuxtImg 
    src="/hero.jpg" 
    loading="eager" 
    fetchpriority="high"
  />
  
  <!-- ✅ Good: responsive with sizes -->
  <NuxtImg 
    src="/product.jpg"
    sizes="(max-width: 640px) 100vw, 50vw"
    :modifiers="{ format: 'webp', quality: 80 }"
  />
</template>

npx nuxi module add @nuxt/fonts

/* Nuxt Fonts will process this automatically */
body {
  font-family: 'Inter', sans-serif;
}

/* Generated automatically */
@font-face {
  font-family: 'Inter Fallback';
  src: local('Arial');
  ascent-override: 90%;
  descent-override: 22%;
  line-gap-override: 0%;
  size-adjust: 107%;
}

# Visualize chunk sizes
npx nuxi analyze

// ❌ Bad: the whole lodash (~70KB)
import _ from 'lodash'

// ✅ Good: only the needed function (~4KB)
import debounce from 'lodash/debounce'

<script setup>
// ❌ Bad: loaded immediately
import { Chart } from 'chart.js'

// ✅ Good: dynamic import
const { Chart } = await import('chart.js')
</script>

# Check for duplicates
npm ls moment
npm ls date-fns

// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            // Move large libraries to separate chunks
            'vendor-chart': ['chart.js'],
            'vendor-editor': ['@tiptap/core', '@tiptap/vue-3']
          }
        }
      }
    }
  }
})

// nuxt.config.ts
export default defineNuxtConfig({
  devtools: { enabled: true }
})

<!-- ❌ Critical mistake -->
<NuxtImg src="/hero.jpg" loading="lazy" />

<!-- ✅ Correct -->
<NuxtImg src="/hero.jpg" fetchpriority="high" />

// ❌ Bad: everything is reactive
const data = ref({
  config: { ... },  // Never changes
  items: []         // Changes
})

// ✅ Good: only what's needed is reactive
const CONFIG = { ... }  // A regular constant
const items = ref([])   // A reactive array

// ❌ Bad: event listener without cleanup
onMounted(() => {
  window.addEventListener('resize', handleResize)
})

// ✅ Good: with cleanup
onMounted(() => {
  window.addEventListener('resize', handleResize)
})
onUnmounted(() => {
  window.removeEventListener('resize', handleResize)
})

// ❌ Bad: blocks rendering
useHead({
  script: [{ src: 'https://analytics.com/script.js' }]
})

// ✅ Good: use Nuxt Scripts
// npx nuxi module add @nuxt/scripts