Lorsque vous ouvrez un projet Laravel moderne, le fichier vite.config.js à la racine peut sembler déroutant au premier abord ; dans cet article, j'explique précisément ce que fait le duo Vite Laravel, pourquoi votre navigateur se met à jour instantanément pendant le développement, et à quoi sert ce mystérieux fichier manifest.json au moment de passer en production. Depuis Laravel 9.19, l'outil de build par défaut n'est plus Laravel Mix basé sur Webpack, mais Vite. Une fois le modèle mental assimilé, la gestion de vos assets CSS et JavaScript devient bien plus agréable.
Qu'est-ce que Vite et pourquoi est-il devenu le défaut de Laravel
Vite est un outil de build frontend créé par Evan You, le créateur de Vue. Il combine deux tâches en un seul outil : un serveur de développement très rapide pendant le dev, et un bundler optimisé basé sur Rollup pour la production. La différence avec les anciens outils est qu'en mode développement, il n'empaquette pas votre code en un gros bundle d'avance. Il s'appuie plutôt sur le support natif des modules ES du navigateur et ne sert les fichiers qu'à la demande. Résultat : même si votre projet grossit, le serveur de dev démarre presque instantanément.
L'intégration avec Laravel est assurée par le paquet laravel-vite-plugin. Ce plugin indique à Vite quels fichiers sont des points d'entrée et communique avec la directive @vite que vous utilisez côté Blade.
Installation et configuration de base
Vite est préinstallé dans un nouveau projet Laravel. Deux commandes suffisent pour installer les dépendances et démarrer le serveur de dev :
npm install
npm run devLe fichier vite.config.js à la racine du projet définit les points d'entrée :
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel({
input: ['resources/css/app.css', 'resources/js/app.js'],
refresh: true,
}),
],
});Ici, le tableau input indique les fichiers principaux que Vite suivra. L'option refresh: true recharge automatiquement le navigateur chaque fois que vous enregistrez des templates Blade, des fichiers de routes ou d'autres sources PHP. Côté Blade, vous incluez vos assets ainsi :
<!DOCTYPE html>
<html>
<head>
@vite(['resources/css/app.css', 'resources/js/app.js'])
</head>La directive @vite est la partie magique : elle adapte son comportement selon l'environnement. En développement, elle pointe vers le serveur Vite, et en production vers les fichiers compilés.
Le HMR en développement : pourquoi le navigateur se met à jour instantanément
Le HMR (Hot Module Replacement) est le mécanisme qui, lorsque vous enregistrez un fichier, injecte uniquement le module modifié dans le navigateur sans recharger toute la page. Lorsque npm run dev s'exécute, Vite ouvre un serveur de dev sur le port 5173 par défaut. En même temps, un petit fichier nommé public/hot est créé à la racine du projet ; il contient l'adresse du serveur de dev.
À chaque rendu de page, la directive @vite vérifie d'abord si ce fichier public/hot existe. Si c'est le cas, elle ne sert pas les assets elle-même ; elle pointe les balises vers le serveur Vite et une connexion WebSocket est établie. Quand vous modifiez un fichier CSS, les styles se mettent à jour sans aucun rechargement de page ; quand vous modifiez un seul module JavaScript, seul ce module change. Cela accélère énormément le flux de développement car l'état de l'application (champs de formulaire, modales ouvertes) est préservé.
- Pas de rechargement complet : seul le module modifié se met à jour, et l'état de la page est conservé.
- Retour instantané : vous voyez le changement dès que vous enregistrez.
- Injection automatique : les nouvelles dépendances
importajoutées sont résolues à la volée.
Bundling et logique du manifest en production
Quand vous êtes prêt à passer en ligne, vous exécutez npm run build. À cette étape, Vite utilise Rollup pour combiner tous les modules, éliminer le code mort (tree-shaking), minifier le JavaScript et le CSS, et ajouter un hash basé sur le contenu aux noms de fichiers. Le résultat est écrit dans le dossier public/build.
Ce hash est crucial : au lieu de app.js, vous obtenez un nom comme app-4ed1f8c2.js. Chaque fois que le contenu du fichier change, le hash change aussi. Cela résout fondamentalement le problème du navigateur et du CDN servant une ancienne version depuis le cache (cache busting). Mais vous ne pouvez pas écrire ce hash aléatoire à la main dans votre template Blade. C'est là qu'intervient le manifest.
À la fin du build, Vite génère public/build/.vite/manifest.json. Ce fichier associe les noms de fichiers sources aux sorties compilées. Un exemple simplifié ressemble à ceci :
{
"resources/js/app.js": {
"file": "assets/app-4ed1f8c2.js",
"isEntry": true,
"css": ["assets/app-1b2c3d4e.css"]
}
}En production, la directive @vite(['resources/js/app.js']) ne trouve pas le fichier public/hot, elle lit donc le manifest. À partir du chemin source, elle trouve le vrai nom de fichier haché et génère les bonnes balises <script> et <link>. Vous écrivez le chemin source, et Laravel résout le bon fichier physique via le manifest. C'est pourquoi le dossier public/build doit toujours être déployé sur le serveur.
Problèmes courants et leurs solutions
L'erreur la plus fréquente dans une configuration Vite Laravel est le message « Unable to locate file in Vite manifest » en production. Elle est presque toujours due au fait que npm run build n'a pas été exécuté, ou que le dossier public/build est absent sur le serveur. Quelques points pratiques :
- Buildez au déploiement : exécutez toujours
npm run buildavant la mise en ligne et envoyez le dossierpublic/build. - Ne commitez pas le fichier
public/hot: s'il reste aprèsnpm run dev, la production cherchera à tort le serveur de dev. Arrêtez le dev proprement avecCtrl+C. Vite::asset()pour les assets statiques : pour pointer vers des fichiers comme des images, placez-les dansresources/et utilisez le helper, ou utilisez directement le dossier public.- Derrière un SSL/proxy : si la connexion HMR ne s'établit pas dans Docker ou un environnement de dev distant, vous devrez peut-être ajuster les réglages
server.hmrdansvite.config.jsselon votre hôte.
Questions fréquentes
Quelle est la différence entre Vite et Laravel Mix ?
Laravel Mix était une surcouche construite au-dessus de Webpack et était lent en développement car il recompilait tout le bundle de zéro. Vite utilise les modules ES natifs en développement, il démarre donc instantanément, et optimise avec Rollup en production. Depuis Laravel 9.19, Vite est le défaut pour les nouveaux projets ; Mix est encore supporté mais Vite est recommandé pour les nouveaux travaux.
Dois-je ajouter le dossier public/build à Git ?
Généralement non. Ce dossier est la sortie compilée et est habituellement ajouté au .gitignore ; à la place, npm run build s'exécute à l'étape de déploiement. Cependant, si vous êtes sur un hébergement mutualisé où vous ne pouvez pas exécuter l'étape de build, committer le dossier et l'envoyer directement est aussi une stratégie valable.
npm run dev et php artisan serve doivent-ils tourner en même temps en développement ?
Oui. php artisan serve (ou votre serveur web) sert l'application PHP, tandis que npm run dev ouvre le serveur Vite dans un terminal séparé et fournit le HMR. Quand les deux tournent ensemble, les pages Blade récupèrent leurs assets depuis le serveur Vite.
Votre processus de build frontend ralentit ou vous rencontrez des erreurs de manifest Vite ? Je peux vous aider sur la configuration de l'asset pipeline, l'automatisation du déploiement et la performance dans les projets Laravel. Contactez-moi et parlons de votre projet.