Nuxt 4 : Nouveautés et Guide de Migration depuis Nuxt 3

Nuxt 4 marque une évolution majeure du framework Vue.js préféré des développeurs. Avec des performances améliorées, une meilleure DX et une compatibilité totale avec Vue 3.5, cette version mérite le détour. Voici tout ce qu'il faut savoir.

Les nouveautés de Nuxt 4

1. Nouvelle structure de dossiers

Nuxt 4 introduit une organisation plus claire :

app/
├── components/
├── composables/
├── layouts/
├── middleware/
├── pages/
├── plugins/
└── app.vue
server/
├── api/
├── middleware/
└── plugins/
shared/
├── types/
└── utils/
nuxt.config.ts

Avantages :

Séparation claire frontend/backend
Dossier shared/ pour le code partagé
Plus intuitif pour les nouveaux développeurs

2. Performances améliorées

Métrique	Nuxt 3	Nuxt 4	Amélioration
Build time	12s	8s	-33%
Cold start	850ms	450ms	-47%
Bundle size	245KB	198KB	-19%
Hydration	180ms	120ms	-33%

3. Compatibilité Vue 3.5

Nuxt 4 tire parti des dernières fonctionnalités de Vue 3.5 :

// Nouvelle syntaxe defineProps avec defaults
const { count = 0, title = 'Default' } = defineProps<{
  count?: number
  title?: string
}>()

// useTemplateRef (remplace ref sur template)
const inputRef = useTemplateRef('input')

// Deferred Teleport
<Teleport to="#modal" defer>
  <Modal />
</Teleport>

4. Nouveau système de layers

Les layers sont maintenant plus puissants :

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '@nuxt/ui-pro', // npm package
    '../base-layer', // dossier local
    'github:user/repo', // GitHub
  ],
  // Les layers peuvent maintenant avoir leurs propres configs
  $production: {
    extends: ['./layers/production']
  }
})

5. Server Components améliorés

<!-- components/HeavyChart.server.vue -->
<script setup lang="ts">
// Ce composant s'exécute uniquement côté serveur
const data = await $fetch('/api/analytics')
</script>

<template>
  <div v-html="renderChart(data)" />
</template>

Avantages :

Pas de JavaScript côté client
Accès direct aux APIs
Performances optimales

6. Nuxt Scripts

Gestion optimisée des scripts tiers :

<script setup lang="ts">
// Chargement optimisé de Google Analytics
useScript('https://www.googletagmanager.com/gtag/js?id=G-XXXXX', {
  trigger: 'onNuxtReady', // ou 'visible', 'idle'
  bundle: true, // bundle avec l'app
})
</script>

Guide de migration Nuxt 3 → Nuxt 4

Étape 1 : Mise à jour des dépendances

# Mettre à jour Nuxt
npx nuxi upgrade --force

# Ou manuellement
npm install nuxt@^4.0.0
npm install vue@^3.5.0

Étape 2 : Activer le mode compatibilité (optionnel)

// nuxt.config.ts
export default defineNuxtConfig({
  future: {
    compatibilityVersion: 4,
  },
  // Mode bridge pour migration progressive
  compatibilityMode: true,
})

Étape 3 : Restructurer les dossiers

# Script de migration automatique
npx nuxi migrate structure

# Ou manuellement :
mkdir -p app server shared
mv components app/
mv composables app/
mv pages app/
mv layouts app/
mv middleware app/
mv plugins app/
mv server/api server/

Étape 4 : Mettre à jour les imports

// Ancien (Nuxt 3)
import { useAsyncData } from '#app'

// Nouveau (Nuxt 4)
import { useAsyncData } from '#imports'
// Ou auto-import (recommandé)

Étape 5 : Adapter les composables

// Ancien
const { data } = await useFetch('/api/users', {
  key: 'users',
  server: true,
})

// Nouveau - getCachedData pour le cache
const { data } = await useFetch('/api/users', {
  key: 'users',
  getCachedData: (key, nuxtApp) => {
    return nuxtApp.payload.data[key] || nuxtApp.static.data[key]
  }
})

Étape 6 : Vérifier les breaking changes

// ❌ Déprécié
useHead({ title: 'Page' })

// ✅ Nouveau
useSeoMeta({
  title: 'Page',
  ogTitle: 'Page',
})

// ❌ Déprécié
definePageMeta({
  key: 'static'
})

// ✅ Nouveau
definePageMeta({
  key: route => route.path
})

Nouvelles fonctionnalités en détail

Data Fetching amélioré

// Nouveau : getCachedData
const { data, refresh, clear } = await useFetch('/api/posts', {
  // Stratégie de cache personnalisée
  getCachedData(key, nuxtApp) {
    const cached = nuxtApp.payload.data[key]
    if (cached && Date.now() - cached.fetchedAt < 60000) {
      return cached
    }
    return null
  },
  // Transform avec types
  transform: (posts): Post[] => posts.map(formatPost),
})

// Nouveau : useRequestFetch pour les requêtes serveur avec cookies
const requestFetch = useRequestFetch()
const user = await requestFetch('/api/me') // Inclut les cookies

Routing amélioré

// pages/users/[id].vue
definePageMeta({
  // Validation des params améliorée
  validate: async (route) => {
    return /^\d+$/.test(route.params.id as string)
  },
  // Nouveau : middleware inline async
  middleware: [
    async (to, from) => {
      const user = await getCurrentUser()
      if (!user) return navigateTo('/login')
    }
  ]
})

Typed Router

// Auto-généré dans .nuxt/typed-router.d.ts
const router = useRouter()

// Autocompletion des routes
router.push({ name: 'users-id', params: { id: '123' } })
//                 ^^^^^^^^ TypeScript connaît les routes

// Typed useRoute
const route = useRoute('users-id')
route.params.id // string, typé automatiquement

Nouveau système de hooks

// plugins/analytics.ts
export default defineNuxtPlugin({
  name: 'analytics',
  enforce: 'pre',
  setup(nuxtApp) {
    // Nouveau hook
    nuxtApp.hook('page:transition:finish', () => {
      trackPageView()
    })

    // Hook avec payload
    nuxtApp.hook('app:rendered', (ctx) => {
      console.log('Rendered in', ctx.renderTime, 'ms')
    })
  }
})

Bonnes pratiques Nuxt 4

1. Utiliser les Server Components

<!-- Pour le contenu statique ou data-heavy -->
<template>
  <div>
    <Header />
    <HeavyDataTable server /> <!-- Rendu serveur uniquement -->
    <Footer />
  </div>
</template>

2. Optimiser le data fetching

// Paralléliser les requêtes
const [users, posts, comments] = await Promise.all([
  useFetch('/api/users'),
  useFetch('/api/posts'),
  useFetch('/api/comments'),
])

// Utiliser useLazyFetch pour le non-critique
const { data: analytics } = await useLazyFetch('/api/analytics')

3. Typed everything

// types/index.ts
export interface User {
  id: number
  name: string
  email: string
}

// composables/useUsers.ts
export const useUsers = () => {
  return useFetch<User[]>('/api/users')
}

FAQ Nuxt 4

Nuxt 4 est-il stable ?

Oui, depuis la sortie officielle. La migration depuis Nuxt 3 est facilitée par le mode compatibilité.

Dois-je migrer immédiatement ?

Non obligatoire. Nuxt 3 reste maintenu. Mais Nuxt 4 apporte des gains de performance significatifs.

Les modules Nuxt 3 sont-ils compatibles ?

La majorité oui. Vérifiez la compatibilité sur nuxt.com/modules avant migration.

Conclusion

Nuxt 4 représente une évolution mature et performante du framework. Les principales raisons de migrer :

-33% de temps de build
-47% de cold start
Meilleure DX avec Vue 3.5
Structure de projet plus claire
Server Components puissants

Commencez par activer le mode compatibilité sur votre projet Nuxt 3, testez, puis migrez progressivement.

Articles connexes :