Le guide parfait pour configurer un nouveau projet Nuxt

Chaque fois que je crée un nouveau projet Nuxt, je suis des étapes spécifiques pour garantir une configuration optimale. Je travaille avec Nuxt depuis 2019 et j'ai développé des habitudes spécifiques lors du démarrage de nouveaux projets.

J'ai pu explorer de nombreux modules et examiner des projets aussi bien d'experts que de débutants. Cela m'a permis de bien comprendre ce qui fonctionne dans l'écosystème Nuxt. Configurer un nouveau projet peut sembler décourageant, surtout pour les débutants, c'est pourquoi j'ai décidé de partager ce guide pour vous aider à configurer votre projet Nuxt aussi efficacement que possible.

Création d'un nouveau projet Nuxt ​

Commençons par créer un nouveau projet Nuxt. C'est l'étape la plus simple, nécessitant juste une commande :

npx nuxi@latest init <nom-du-projet>

L'exécution de cette commande va créer un nouveau projet Nuxt dans le répertoire <nom-du-projet>. L'application est minimaliste : aucune configuration, aucun module, juste Nuxt et un fichier app.vue.

Mettre à jour les dépendances ​

Avant de continuer, il est essentiel de mettre à jour les dépendances vers leurs dernières versions. Cela vous permet de tirer parti des nouvelles fonctionnalités et correctifs tout en évitant des dépendances obsolètes qui pourraient causer des problèmes par la suite. Exécutez la commande suivante pour les mettre à jour :

npx taze -w

Le paquet taze, développé par Anthony Fu, met à jour toutes les dépendances vers leurs dernières versions. C'est similaire à npm-check-updates mais plus puissant grâce à son respect version avec semver tout en étant plus rapide.

Préparer pour Nuxt 4 ​

Actuellement, la dernière version stable de Nuxt est la version 3. Cependant, la version 4 est en développement et promet de nombreuses fonctionnalités et améliorations. Bien qu'elle ne soit pas officiellement publiée, vous pouvez préparer vos projets pour cette future mise à jour en ajoutant la configuration suivante dans votre nuxt.config.js :

export default defineNuxtConfig({
  future: {
    compatibilityVersion: 4,
  }
})

Cette configuration vous permet de commencer à développer vos projets comme si vous utilisiez déjà Nuxt 4. Cette prévoyance vous permet non seulement de bénéficier des fonctionnalités à venir, mais aussi de minimiser le travail requis pour la mise à niveau lorsque Nuxt 4 sera publié.

Pour tirer le meilleur parti de Nuxt 4, créez un nouveau dossier app et déplacez le fichier app.vue à l'intérieur :

mkdir app && mv app.vue app

Linting et formatage ​

Nuxt offre une excellente expérience développeur pour le linting et le formatage. Installez à la fois le linter et le formateur avec la commande suivante :

npx nuxi module add eslint && npx @antfu/ni -D typescript

Cette commande installe le module @nuxt/eslint, qui propose une configuration ESLint sans configuration pour les projets Nuxt. Activez le formatage, et il corrigera automatiquement les problèmes lors de l'enregistrement d'un fichier. Je le configure toujours dans mon nuxt.config.ts :

export default defineNuxtConfig({
  eslint: {
    config: {
      stylistic: true
    }
  }
})

De plus, créez un fichier .vscode/settings.json pour désactiver l'extension prettier, évitant les conflits avec le formateur ESLint :

{
  "prettier.enable": false
}

Ajoutez deux scripts à votre fichier package.json :

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint --fix ."
  }
}

Maintenant, vous pouvez exécuter pnpm run lint pour vérifier les erreurs et pnpm run lint:fix pour les corriger.

Ces configurations prédéfinies facilitent la mise en place de ESLint avec un support pour TypeScript et Vue, garantissant un code cohérent et propre.

UI et composants ​

Avec une configuration de projet propre, les dernières dépendances, la préparation pour Nuxt 4, et un linting et formatage robustes, il est temps de se concentrer sur l'UI et les composants. Cette étape varie en fonction des objectifs du projet et des exigences de conception.

Nuxt UI et Nuxt UI Pro ​

Si le projet met l'accent sur la logique métier plutôt que sur l'UI, j'utilise les bibliothèques de composants Nuxt UI et Nuxt UI Pro. Elles sont bien conçues et faciles à utiliser. Lire le code source de Nuxt UI est instructif, et si vous voulez plongez davantage dans les composants, j'ai écris un article à ce sujet.

Tout d'abord, installez Nuxt UI et Tailwind CSS :

pnpm add @nuxt/ui@next tailwindcss@next

Ajoutez le module à votre fichier nuxt.config.ts :

export default defineNuxtConfig({
  modules: ['@nuxt/ui']
})

Importez le CSS nécessaire dans votre fichier app/assets/css/main.css :

@import "tailwindcss";
@import "@nuxt/ui";

Assurez-vous que ce fichier CSS est inclus dans le fichier nuxt.config.ts :

export default defineNuxtConfig({
  css: ['~/assets/css/main.css']
})

Mettez à jour votre fichier .vscode/settings.json pour améliorer l'expérience avec l'extension Tailwind CSS IntelliSense :

{
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  }
}

Enfin, modifiez votre fichier app/app.vue pour inclure le composant Nuxt UI <UApp>, injectant automatiquement des composants globaux :

<template>
  <UApp>
    <NuxtPage />
  </UApp>
</template>

Tailwind CSS ​

Pour les projets nécessitant des conceptions spécifiques ou lorsque je collabore avec des designers, je me tourne vers Tailwind CSS. Il s'agit d'un cadre CSS utilitaire qui rationalise le processus de conception à tel point qu'il est inimaginable de travailler sans. La version à venir, Tailwind CSS 4, inclut un plugin Vite indispensable, éliminant le besoin de modules supplémentaires et simplifiant la configuration.

Installez la dernière version de Tailwind CSS :

pnpm add tailwindcss@next @tailwindcss/vite

Créez un fichier app/assets/css/main.css et importez Tailwind CSS :

@import "tailwindcss";

Mettez à jour votre fichier nuxt.config.ts pour utiliser le plugin Vite :

import Tailwind from '@tailwindcss/vite'

export default defineNuxtConfig({
  css: ['~/assets/css/main.css'],
  vite: {
    plugins: [
      Tailwind()
    ]
  }
})

Améliorez votre expérience développeur en mettant à jour votre fichier .vscode/settings.json pour l'extension Tailwind CSS IntelliSense :

{
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  }
}

La configuration est incroyablement simple !

Icônes ​

Incorporer des icônes dans votre projet est essentiel, bien que cela puisse s'avérer trompeusement complexe. L'article d'Anthony Fu explique comment il a trouvé la solution d'icônes parfaite.

Si vous utilisez Nuxt UI, les icônes sont déjà inclus. Vous pouvez donc ignorer cette section.

Pour les utilisateurs de Tailwind CSS, deux options sont disponibles :

1. Utiliser le module Nuxt Icons fournit accès à plus de 200 000 icônes de divers ensembles d'icônes :

npx nuxi module add icon

C'est la solution la plus simple et avec les dernières améliorations de la v1, c'est un choix puissant. Je recommande de commencer par cette option.

2. Utiliser le plugin Tailwind CSS, Tailwind CSS Icons, offre des icônes similaires via une approche différente :

npx @antfu/ni -D @egoist/tailwindcss-icons

Créez un fichier tailwind.config.js et incluez le plugin :

import { getIconCollections, iconsPlugin } from '@egoist/tailwindcss-icons'

/** @type {import('tailwindcss').Config} */
module.exports = {
  plugins: [
    iconsPlugin({
      collections: getIconCollections([/** ... */]),
    }),
  ],
}

Importez la configuration dans votre fichier app/assets/css/main.css :

@import "tailwindcss";
@config "../../../tailwind.config.js";

Personnellement, je préfère la deuxième solution en raison de sa configuration uniforme à travers les projets, y compris ceux n'utilisant pas Nuxt, et au moment où j'ai fait ce choix, le module Nuxt Icons souffrait de nombreux inconvénients. Cependant, ce n'est plus le cas et je vous recommande fortement de commencer par Nuxt Icons.

Polices ​

Les polices définissent la personnalité de votre projet et influencent la perception utilisateur. Nuxt fournit une solution : Nuxt Fonts. Ce module zéro configuration charge automatiquement les polices requises en scannant les fichiers CSS. L'installation est simple :

npx nuxi module add fonts

Ce module fait partie de mes projets sauf si j'utilise Nuxt UI, où il est inclus. Mais je dois dire que j'ai rarement besoin de l'installer puisque Nuxt UI suffit dans la plupart des scénarios.

CI ​

Pour mes projets personnels, j'utilise GitHub et je configure toujours un CI pour faire respecter le linting et corriger automatiquement les erreurs. Cette approche assure un code propre et cohérent. Bien que les linters et formatters soient excellents, ils sont inutiles s'ils ne sont pas utilisés.

J'utilise GitHub Actions, détaillées dans un fichier .github/workflows/ci.yml :

name: CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  lint:
    name: Lint
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
      - run: corepack enable
      - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4
        with:
          node-version: 22
          cache: pnpm

      - name: Installer les dépendances
        run: pnpm install

      - name: Linter les fichiers
        run: pnpm run lint

Pour automatiser le formatage du code et les commits, j'utilise autofix.ci :

name: autofix.ci # needed to securely identify the workflow

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  autofix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
      - run: corepack enable
      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4
        with:
          node-version: 20.5
          cache: pnpm

      - name: Installer les dépendances
        run: pnpm install

      - name: Linter et corriger
        run: pnpm run lint:fix

      - uses: autofix-ci/action@ff86a557419858bb967097bfc916833f5647fa8c

Garder les dépendances à jour ​

Maintenir des dépendances à jour est crucial. Avec de nombreux projets, cela peut prendre beaucoup de temps. J'utilise Renovate dans chaque projet pour automatiser les mises à jour des dépendances :

Créez un fichier renovate.json avec :

{
  "extends": [
    "github>nuxt/renovate-config-nuxt"
  ]
}

Cet outil est indispensable, et je trouve difficile de travailler sur des projets ne disposant pas de Renovate (comme certains projets professionnels).

Astuces, conseils et considérations supplémentaires ​

Voici quelques astuces et conseils supplémentaires que je trouve utiles à toujours avoir en tête, même s'ils ne sont pas directement liés à la configuration :

Toujours placer les scripts en premier ​

Organisez les fichiers vue en plaçant la section script en premier. Cela offre de la clarté en présentant la logique de composant avant le template :

<script lang="ts">
// ...
</script>

<template>
  // ...
</template>

Adoptez TypeScript ​

Je plaide pour l'utilisation de TypeScript dans tous les fichiers vue et les scripts utilitaires ou composables. Ajouter lang="ts" même sans code TypeScript améliore l'expérience développeur :

<script lang="ts" setup>
// ...
</script>

Évitez d'utiliser process.env dans nuxt.config.ts ​

Évitez d'accéder directement à process.env dans nuxt.config.ts. Par exemple, définir des valeurs par défaut pour runtimeConfig ne doit pas utiliser process.env :

export default defineNuxtConfig({
  runtimeConfig: {
    apiUrl: ''
  }
})

Créez un fichier .env à la racine du projet pour définir les variables d'environnement :

NUXT_API_URL=https://api.example.com

Excluez le fichier .env à l'aide de .gitignore :

echo ".env" >> .gitignore

Fournissez un fichier .env.example pour guider les autres développeurs :

NUXT_API_URL=https://api.example.com

Auditor avant d'installer des modules ​

Réalisez un audit avant d'ajouter de nouveaux modules pour évaluer leur nécessité et fonctionnalité. Parfois, il est possible de procéder sans eux ou de choisir une alternative supérieure. Évitez de baser vos décisions sur des étoiles ou des téléchargements. Parcourez plutôt la documentation, le code source, les problèmes et les PR pour une évaluation complète du projet. L'écosystème Nuxt évolue rapidement, et certains modules peuvent devenir obsolètes ou incompatibles avec les nouvelles versions de Nuxt.

Choisir entre useFetch et $fetch ​

Évitez d'utiliser fetch directement ; optez pour $fetch, une instance de ofetch.

Pour savoir lequel utiliser, voici un guide rapide :

1. Utilisez $fetch pour les opérations côté client, telles que les soumissions de données de formulaire.
2. Utilisez useFetch lorsque le rendu côté serveur est envisageable, comme lors de la récupération de données d'API à afficher sur des pages.

La configuration parfaite est à vous ​

Ce guide incarne tout ce que je fais pour initier un nouveau projet Nuxt. Cette configuration complète prend environ 10 minutes, ce qui donne un projet propre, puissant et prêt pour l'avenir, permettant de se concentrer sur la logique métier sans distractions.

J'espère que ce guide améliorera votre configuration de projet Nuxt. Si vous avez des questions ou souhaitez partager votre configuration, veuillez laisser un commentaire ci-dessous.