Nuxt.js : Le Guide Complet pour Débutants (2025)

Nuxt.js est le framework de référence pour créer des applications Vue.js performantes et optimisées pour le SEO. Créé par Sébastien Chopin en 2016, Nuxt simplifie le développement en offrant une expérience "batteries included".

Dans ce guide complet, vous apprendrez tout ce qu'il faut savoir pour démarrer avec Nuxt.js en 2025.

Qu'est-ce que Nuxt.js ?

Nuxt.js est un framework fullstack basé sur Vue.js qui offre :

SSR (Server-Side Rendering) : Pages rendues côté serveur pour un meilleur SEO
SSG (Static Site Generation) : Sites statiques ultra-rapides
Auto-imports : Composants et composables importés automatiquement
Routing automatique : Routes générées depuis le système de fichiers
API Routes : Backend intégré sans serveur séparé

Installation de Nuxt.js

Créer un nouveau projet

# Créer un projet Nuxt 3
npx nuxi@latest init mon-projet

# Se déplacer dans le dossier
cd mon-projet

# Installer les dépendances
npm install

# Lancer le serveur de développement
npm run dev

Ouvrez http://localhost:3000 pour voir votre application Nuxt.js !

Structure du projet Nuxt.js

mon-projet/
├── .nuxt/              # Fichiers générés (ne pas modifier)
├── assets/             # CSS, images compilées par Vite
├── components/         # Composants Vue (auto-importés)
├── composables/        # Fonctions réutilisables (auto-importées)
├── content/            # Fichiers Markdown (avec Nuxt Content)
├── layouts/            # Mises en page
├── middleware/         # Middleware de navigation
├── pages/              # Routes de l'application
├── plugins/            # Plugins Vue/Nuxt
├── public/             # Fichiers statiques
├── server/             # API et logique serveur
├── app.vue             # Composant racine
├── nuxt.config.ts      # Configuration Nuxt
└── package.json

Routing avec Nuxt.js

Le routing est automatique dans Nuxt.js. Créez des fichiers dans pages/ et les routes sont générées.

Routes basiques

pages/
├── index.vue           → /
├── about.vue           → /about
├── contact.vue         → /contact
└── blog/
    ├── index.vue       → /blog
    └── [slug].vue      → /blog/:slug

Exemple de page

<!-- pages/index.vue -->
<template>
  <div class="home">
    <h1>Bienvenue sur mon site Nuxt.js</h1>
    <p>{{ message }}</p>
    <NuxtLink to="/about">À propos</NuxtLink>
  </div>
</template>

<script setup>
const message = ref('Nuxt.js est génial !')
</script>

Routes dynamiques

<!-- pages/blog/[slug].vue -->
<template>
  <article>
    <h1>{{ article.title }}</h1>
    <div v-html="article.content"></div>
  </article>
</template>

<script setup>
const route = useRoute()

// Récupérer l'article depuis l'API
const { data: article } = await useFetch(`/api/articles/${route.params.slug}`)
</script>

Composants dans Nuxt.js

Les composants sont auto-importés depuis le dossier components/.

Créer un composant

<!-- components/Card.vue -->
<template>
  <div class="card">
    <h3>{{ title }}</h3>
    <p>{{ description }}</p>
    <slot />
  </div>
</template>

<script setup>
defineProps({
  title: String,
  description: String
})
</script>

<style scoped>
.card {
  padding: 1rem;
  border: 1px solid #eee;
  border-radius: 8px;
}
</style>

Utiliser le composant

<!-- pages/index.vue -->
<template>
  <div>
    <!-- Pas besoin d'import ! -->
    <Card title="Mon titre" description="Ma description">
      <button>Action</button>
    </Card>
  </div>
</template>

Data Fetching avec useFetch

useFetch est le composable recommandé pour récupérer des données.

<script setup>
// Récupération simple
const { data: users } = await useFetch('/api/users')

// Avec options
const { data, pending, error, refresh } = await useFetch('/api/products', {
  query: { category: 'electronics' },
  transform: (response) => response.items
})
</script>

<template>
  <div>
    <p v-if="pending">Chargement...</p>
    <p v-else-if="error">Erreur : {{ error.message }}</p>
    <ul v-else>
      <li v-for="user in users" :key="user.id">
        {{ user.name }}
      </li>
    </ul>
    <button @click="refresh">Rafraîchir</button>
  </div>
</template>

API Routes avec Nuxt.js

Créez des endpoints API dans le dossier server/api/.

GET Request

// server/api/users.get.ts
export default defineEventHandler(async () => {
  return [
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' }
  ]
})

POST Request

// server/api/users.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event)

  // Validation
  if (!body.name || !body.email) {
    throw createError({
      statusCode: 400,
      message: 'Nom et email requis'
    })
  }

  // Créer l'utilisateur (simulé)
  return { id: 3, ...body }
})

Route dynamique

// server/api/users/[id].get.ts
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')

  // Récupérer l'utilisateur depuis la base de données
  const user = await prisma.user.findUnique({ where: { id } })

  if (!user) {
    throw createError({
      statusCode: 404,
      message: 'Utilisateur non trouvé'
    })
  }

  return user
})

Layouts dans Nuxt.js

Les layouts permettent de réutiliser une structure de page.

Layout par défaut

<!-- layouts/default.vue -->
<template>
  <div class="layout">
    <header>
      <nav>
        <NuxtLink to="/">Accueil</NuxtLink>
        <NuxtLink to="/about">À propos</NuxtLink>
        <NuxtLink to="/contact">Contact</NuxtLink>
      </nav>
    </header>

    <main>
      <slot />
    </main>

    <footer>
      <p>&copy; 2025 Mon Site</p>
    </footer>
  </div>
</template>

Layout personnalisé

<!-- layouts/admin.vue -->
<template>
  <div class="admin-layout">
    <Sidebar />
    <div class="content">
      <slot />
    </div>
  </div>
</template>

<!-- pages/dashboard.vue -->
<script setup>
definePageMeta({
  layout: 'admin'
})
</script>

<template>
  <div>Dashboard admin</div>
</template>

SEO avec Nuxt.js

Nuxt.js excelle pour le SEO grâce au SSR.

<script setup>
// Meta basique
useHead({
  title: 'Ma Page - Mon Site',
  meta: [
    { name: 'description', content: 'Description de ma page' }
  ]
})

// SEO avancé avec useSeoMeta
useSeoMeta({
  title: 'Mon Article | Blog',
  ogTitle: 'Mon Article | Blog',
  description: 'Description de l\'article',
  ogDescription: 'Description pour les réseaux sociaux',
  ogImage: '/images/article.jpg',
  twitterCard: 'summary_large_image'
})
</script>

Configuration nuxt.config.ts

// nuxt.config.ts
export default defineNuxtConfig({
  // Modules Nuxt
  modules: [
    '@nuxtjs/tailwindcss',
    '@pinia/nuxt',
    '@nuxt/image'
  ],

  // Variables d'environnement
  runtimeConfig: {
    // Côté serveur uniquement
    apiSecret: process.env.API_SECRET,

    // Côté client et serveur
    public: {
      apiBase: process.env.API_BASE || 'https://api.example.com'
    }
  },

  // SSR activé (par défaut)
  ssr: true,

  // Options Nitro (serveur)
  nitro: {
    preset: 'vercel' // ou 'netlify', 'cloudflare', etc.
  }
})

Déploiement Nuxt.js

Génération statique (SSG)

# Générer le site statique
npm run generate

# Les fichiers sont dans .output/public/

Build serveur (SSR)

# Build pour le serveur
npm run build

# Tester localement
npm run preview

# Déployer .output/

Plateformes supportées

Vercel : npx nuxi deploy vercel
Netlify : Configuration automatique
Cloudflare Pages : Support edge
AWS : Lambda, Amplify
Docker : Image Node.js

Modules Nuxt.js populaires

Module	Description
`@nuxtjs/tailwindcss`	Intégration Tailwind CSS
`@pinia/nuxt`	State management
`@nuxt/image`	Optimisation images
`@nuxt/content`	CMS basé sur Markdown
`@nuxtjs/i18n`	Internationalisation
`@sidebase/nuxt-auth`	Authentification

Conclusion

Nuxt.js est le framework idéal pour créer des applications Vue.js modernes et performantes. Avec son routing automatique, ses auto-imports et son SSR natif, vous pouvez vous concentrer sur le code qui compte.

Prochaines étapes :