Bundling des assets avec Vite - Knowledge of Laravel

Laravel et Vite

Vite est un outil de build frontend rapide. En développement, il propose du Hot Module Replacement (HMR) qui applique instantanément les changements de fichiers ; en production, il génère des assets optimisés. Depuis Laravel 9, Vite est l’outil de build officiel, intégré à Laravel via laravel-vite-plugin. Ce plugin :

gère les points d’entrée ;
fournit le HMR pendant le développement ;
s’intègre à la directive Blade @vite() ;
gère la versioning des assets en production (cache-busting).

Avec un kit de démarrage (Laravel Breeze, etc.), la configuration Vite + Tailwind est déjà en place. Cette page décrit la configuration à partir de zéro.

Pour situer Vite dans l’architecture frontend Laravel, consultez d’abord Frontend.

Installation et configuration

Vérifier Node

Node.js 16+ et npm sont requis.

node -v
npm -v

Installer les paquets

Un projet Laravel neuf a déjà vite et laravel-vite-plugin dans package.json. Installez :

npm install

`vite.config.js`

Le fichier est présent à la racine. Spécifiez vos points d’entrée.

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
        ]),
    ],
});

Pour un SPA / Inertia, il est conseillé d’importer le CSS depuis le JS. Retirez resources/css/app.css de la liste et ajoutez import '../css/app.css'; en tête de resources/js/app.js.

Démarrer le serveur de dev

En dev, npm run dev lance le serveur Vite. Les modifications se rechargent automatiquement (HMR).

npm run dev

Lancez aussi le serveur Laravel avec composer run dev.

composer run dev

composer run dev démarre php artisan serve et npm run dev en parallèle.

Rechargement automatique des vues Blade

refresh: true recharge automatiquement le navigateur lorsque vous sauvegardez une vue Blade ou un fichier de route.

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,
        }),
    ],
});

Répertoires surveillés avec refresh: true :

resources/views/**
app/Livewire/**
routes/**
lang/**

Build de production

Avant le déploiement, lancez npm run build. Les assets sont bundlés et versionnés dans public/build/.

npm run build

Structure typique :

public/
  build/
    assets/
      app-Cv82Mlke.css
      app-DnAZBF4U.js
    manifest.json

manifest.json fait la correspondance nom → hash ; @vite() s’en sert pour charger les bons fichiers.

Ajoutez public/build/ à .gitignore. Buildez à la volée sur le serveur ou via CI.

Charger les assets depuis Blade

Ajoutez @vite() dans le <head> de votre layout.

<!DOCTYPE html>
<html lang="fr">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ config('app.name') }}</title>

    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>
<body>
    @yield('content')
</body>
</html>

Si le CSS est importé depuis le JS, ne référencez que l’entrée JavaScript.

@vite('resources/js/app.js')

La directive @vite() change de comportement selon l’environnement.

Contexte	Comportement
Serveur de dev actif	Charge depuis Vite, HMR activé
Production (build)	Consulte `public/build/manifest.json`

Points d’entrée JS / CSS

JavaScript

resources/js/app.js est le point d’entrée principal ; importez-y les autres modules.

import './bootstrap';
import '../css/app.css';

// Modules maison
import './components/modal';
import './utils/format';

CSS

Placez les styles globaux dans resources/css/app.css.

/* Tailwind CSS */
@import 'tailwindcss';

/* Styles personnalisés */
body {
    font-family: 'Inter', sans-serif;
}

Plusieurs points d’entrée

Pour un back-office avec ses propres assets :

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
    plugins: [
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
            'resources/css/admin.css',
            'resources/js/admin.js',
        ]),
    ],
});

Dans les layouts Blade, chargez seulement le bon point d’entrée.

{{-- Layout admin --}}
@vite(['resources/css/admin.css', 'resources/js/admin.js'])

Intégration Tailwind CSS

Tailwind v4 s’intègre via un plugin Vite.

Installer Tailwind

npm install tailwindcss @tailwindcss/vite

Ajouter le plugin à `vite.config.js`

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
    plugins: [
        tailwindcss(),
        laravel([
            'resources/css/app.css',
            'resources/js/app.js',
        ]),
    ],
});

Importer Tailwind dans le CSS

/* resources/css/app.css */
@import 'tailwindcss';

Tailwind v3 nécessitait tailwind.config.js et postcss.config.js. Tailwind v4 n’en a plus besoin.

Alias

laravel-vite-plugin configure automatiquement l’alias @ vers resources/js.

import UserCard from '@/components/UserCard.vue';
// équivaut à
import UserCard from '/resources/js/components/UserCard.vue';

Alias personnalisés via resolve.alias :

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import path from 'path';

export default defineConfig({
    plugins: [
        laravel(['resources/js/app.js']),
    ],
    resolve: {
        alias: {
            '@': '/resources/js',
            '@css': '/resources/css',
            '@images': '/resources/images',
        },
    },
});

Exemple :

import logo from '@images/logo.png';
import '@css/custom.css';

Configurations par framework

Vue

npm install --save-dev @vitejs/plugin-vue

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
    plugins: [
        laravel(['resources/js/app.js']),
        vue({
            template: {
                transformAssetUrls: {
                    base: null,
                    includeAbsolute: false,
                },
            },
        }),
    ],
});

React

npm install --save-dev @vitejs/plugin-react

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import react from '@vitejs/plugin-react';

export default defineConfig({
    plugins: [
        laravel(['resources/js/app.jsx']),
        react(),
    ],
});

Ajoutez @viteReactRefresh avant @vite dans le template Blade.

@viteReactRefresh
@vite('resources/js/app.jsx')

Assets statiques

Les images et polices référencées depuis Blade peuvent aussi être versionnées. Précisez les répertoires via assets.

laravel({
    input: 'resources/js/app.js',
    assets: ['resources/images/**', 'resources/fonts/**'],
})

Récupérez l’URL versionnée avec Vite::asset().

<img src="{{ Vite::asset('resources/images/logo.png') }}" alt="Logo">

Récapitulatif

Objectif	Méthode
Serveur de dev	`npm run dev`
Build de production	`npm run build`
Charger les assets	`@vite(['resources/css/app.css', 'resources/js/app.js'])`
Auto-reload sur Blade	`refresh: true` dans `vite.config.js`
Tailwind CSS	plugin `@tailwindcss/vite`
Alias `@`	vers `resources/js` par défaut
Versioner des assets statiques	Option `assets` et `Vite::asset()`

Prochaines étapes

Cache

Améliorez encore les performances de votre application grâce au cache Laravel.

​Laravel et Vite

​Installation et configuration

​Vérifier Node

​Installer les paquets

​vite.config.js

​Démarrer le serveur de dev

​Rechargement automatique des vues Blade

​Build de production

​Charger les assets depuis Blade

​Points d’entrée JS / CSS

​JavaScript

​CSS

​Plusieurs points d’entrée

​Intégration Tailwind CSS

​Alias

​Configurations par framework

​Vue

​React

​Assets statiques

​Récapitulatif

​Prochaines étapes

Cache

Laravel et Vite

Installation et configuration

Vérifier Node

Installer les paquets

`vite.config.js`

Démarrer le serveur de dev

Rechargement automatique des vues Blade

Build de production

Charger les assets depuis Blade

Points d’entrée JS / CSS

JavaScript

CSS

Plusieurs points d’entrée

Intégration Tailwind CSS

Alias

Configurations par framework

Vue

React

Assets statiques

Récapitulatif

Prochaines étapes