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>
npx nuxi init nuxt-app -t v4-compat, ce qui vous évite la nécessité de Préparer pour Nuxt 4.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
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 :
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@next
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 :
- 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.
- 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>
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 :
export default defineNuxtConfig({
runtimeConfig: {
apiUrl: ''
}
})
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 :
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 :
- Utilisez
$fetchpour les opérations côté client, telles que les soumissions de données de formulaire. - Utilisez
useFetchlorsque 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.
Discussions
Chargement des discussions...
Ajouter un commentaire
Vérification de votre session...