--- contentId: 1bc3959e-9b88-4fd7-9898-cb60cb3420ff title: "Le guide parfait pour configurer un nouveau projet Nuxt" description: "Un guide complet pour configurer efficacement un projet Nuxt, garantissant un projet propre, performant et prêt pour l'avenir." date: 2024-12-21 --- 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 : ```bash npx nuxi@latest init ``` > [!TIP] > Vous pouvez également créer un projet prêt pour la v4 avec `npx nuxi init nuxt-app -t v4-compat`, ce qui vous évite la nécessité de [Préparer pour Nuxt 4](#preparer-pour-nuxt-4). > [!NOTE] > Je choisis toujours **pnpm** comme gestionnaire de paquets. Vous pouvez sélectionner celui que vous préférez, mais je recommande d'essayer **pnpm**. L'exécution de cette commande va créer un nouveau projet Nuxt dans le répertoire ``. 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 : ```bash npx taze -w ``` Le paquet **taze**, développé par [Anthony Fu](https://antfu.me), 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` : ```ts 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 : ```bash mkdir app && mv app.vue app ``` > [!TIP] > Vous pouvez également créer un projet prêt pour la v4 en utilisant la commande `npx nuxi init nuxt-app -t v4-compat`. ## 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 : ```bash 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](https://eslint.nuxt.com). 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` : ```ts export default defineNuxtConfig({ eslint: { config: { stylistic: true // [!code highlight] } } }) ``` De plus, créez un fichier `.vscode/settings.json` pour désactiver l'extension prettier, évitant les conflits avec le formateur ESLint : ```json { "prettier.enable": false } ``` Ajoutez deux scripts à votre fichier `package.json` : ```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](https://ui.nuxt.com) et Nuxt UI Pro. Elles sont bien conçues et faciles à utiliser. Lire le [code source de Nuxt UI](https://github.com/nuxt/ui) est instructif, et si vous voulez plongez davantage dans les composants, j'ai écris un article à ce sujet. > [!NOTE] > Au moment de la rédaction, Nuxt UI 3 n'est pas officiellement publié, mais il peut être utilisé dans les projets. Si vous lisez cela plus tard, laissez-moi un commentaire, et je mettrai à jour ce guide. Tout d'abord, installez Nuxt UI et Tailwind CSS : ```bash pnpm add @nuxt/ui@next tailwindcss@next ``` Ajoutez le module à votre fichier `nuxt.config.ts` : ```ts export default defineNuxtConfig({ modules: ['@nuxt/ui'] }) ``` Importez le CSS nécessaire dans votre fichier `app/assets/css/main.css` : ```css @import "tailwindcss"; @import "@nuxt/ui"; ``` Assurez-vous que ce fichier CSS est inclus dans le fichier `nuxt.config.ts` : ```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](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) : ```json { "files.associations": { "*.css": "tailwindcss" }, "editor.quickSuggestions": { "strings": "on" } } ``` Enfin, modifiez votre fichier `app/app.vue` pour inclure le composant Nuxt UI ``, injectant automatiquement des composants globaux : ```vue ``` > [!NOTE] > Nuxt UI Pro est une extension payante offrant des composants de mise en page pour un développement d'application rapide. C'est un investissement valable qui fait gagner du temps et des efforts tout en soutenant l'équipe Nuxt et le développement open-source. 💚 ### Tailwind CSS Pour les projets nécessitant des conceptions spécifiques ou lorsque je collabore avec des designers, je me tourne vers [Tailwind CSS](https://tailwindcss.com). 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 : ```bash pnpm add tailwindcss@next @tailwindcss/vite@next ``` Créez un fichier `app/assets/css/main.css` et importez Tailwind CSS : ```css @import "tailwindcss"; ``` Mettez à jour votre fichier `nuxt.config.ts` pour utiliser le plugin Vite : ```ts 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](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) : ```json { "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](https://nuxt.com/blog/nuxt-icon-v1-0) 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](https://github.com/nuxt/icon) fournit accès à plus de 200 000 icônes de divers ensembles d'icônes : ```bash 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](https://github.com/egoist/tailwindcss-icons), offre des icônes similaires via une approche différente : ```bash npx @antfu/ni -D @egoist/tailwindcss-icons ``` Créez un fichier `tailwind.config.js` et incluez le plugin : ```js 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` : ```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](https://github.com/nuxt/icon). ## Polices Les polices définissent la personnalité de votre projet et influencent la perception utilisateur. **Nuxt** fournit une solution : [Nuxt Fonts](https://fonts.nuxt.com/). Ce module zéro configuration charge automatiquement les polices requises en scannant les fichiers CSS. L'installation est simple : ```bash 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` : ```yaml 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](https://autofix.ci/) : ```yaml 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](https://docs.renovatebot.com/) dans chaque projet pour automatiser les mises à jour des dépendances : Créez un fichier `renovate.json` avec : ```json { "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 : ```vue ``` ### 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 : ```vue ``` > [!NOTE] > Optez toujours pour la syntaxe `setup` dans les composants. ### É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` : ```ts export default defineNuxtConfig({ runtimeConfig: { apiUrl: '' } }) ``` > [!TIP] > Survolez la clé `apiUrl` dans votre IDE pour des indices sur les variables d'environnement. Dans ce cas **Nuxt** vous informe que la variable d'environnement doit avoir le nom `NUXT_API_URL`. 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` : ```bash 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**](https://github.com/unjs/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. > [!WARNING] > Évitez de créer un template à partir de ce guide. L'écosystème est dynamique, et de nouveaux modules émergent rapidement. Chaque projet peut nécessiter des ajustements nuancés. Ce guide est un point de départ, une liste de vérification pour la configuration initiale. Cependant, adaptez toujours en fonction des besoins spécifiques du projet. Maintenir un modèle nécessite des efforts et n'est généralement pas rentable. 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.