Sur un thème WordPress compilé avec webpack, chaque modification d’un fichier Sass déclenchait un rebuild de deux à trois secondes avant que le navigateur ne se rafraîchisse. Rien de bloquant isolément, mais cumulé sur une journée de travail, cette latence casse la concentration. Vite change fondamentalement l’approche : en développement, il sert les modules ES nativement au navigateur sans bundling préalable, ce qui ramène le temps de rechargement à quelques dizaines de millisecondes, quelle que soit la taille du projet.
Ce tutoriel couvre l’intégration de Vite dans un thème classique — configuration, lecture du manifeste en PHP, gestion du serveur de développement. L’intégration avec l’éditeur de blocs, qui pose des contraintes différentes, n’est pas abordée ici.
Installer et configurer Vite
L’intégration officielle pour un usage hors framework front passe par le paquet vite seul, sans plugin spécifique WordPress — il n’en existe pas d’officiel, la configuration se fait à la main :
npm install --save-dev vite
Le fichier vite.config.js à la racine du thème :
import { defineConfig } from 'vite';
export default defineConfig({
base: '/wp-content/themes/mon-theme/dist/',
build: {
manifest: true,
outDir: 'dist',
rollupOptions: {
input: {
main: 'assets/js/main.js',
style: 'assets/scss/style.scss',
},
},
},
server: {
origin: 'http://localhost:5173',
},
});
L’option manifest: true est la pièce centrale de l’intégration : elle génère, à chaque build de production, un fichier manifest.json qui associe chaque fichier source à son fichier compilé final, avec son hash d’invalidation de cache.
Lire le manifeste en PHP
WordPress n’a aucune connaissance native de Vite. Il faut donc écrire une fonction qui lit manifest.json et enqueue les bons fichiers, en distinguant développement et production :
function mon_theme_enqueue_vite_assets() {
$is_dev = file_exists( get_template_directory() . '/.vite-dev' );
if ( $is_dev ) {
wp_enqueue_script( 'vite-client', 'http://localhost:5173/@vite/client', array(), null, true );
wp_enqueue_script( 'mon-theme-main', 'http://localhost:5173/assets/js/main.js', array(), null, true );
return;
}
$manifest_path = get_template_directory() . '/dist/manifest.json';
if ( ! file_exists( $manifest_path ) ) {
return;
}
$manifest = json_decode( file_get_contents( $manifest_path ), true );
wp_enqueue_style(
'mon-theme-style',
get_template_directory_uri() . '/dist/' . $manifest['assets/scss/style.scss']['file'],
array(),
null
);
wp_enqueue_script(
'mon-theme-main',
get_template_directory_uri() . '/dist/' . $manifest['assets/js/main.js']['file'],
array(),
null,
true
);
}
add_action( 'wp_enqueue_scripts', 'mon_theme_enqueue_vite_assets' );
Les scripts servis en mode développement doivent être déclarés avec l’attribut type="module", que wp_enqueue_script() ne gère pas nativement avant WordPress 6.5 et son support des types de script — un filtre sur script_loader_tag reste nécessaire sur les versions antérieures pour ajouter cet attribut manuellement.
Basculer entre développement et production
Le fichier marqueur .vite-dev, créé ou supprimé selon le contexte, offre un moyen simple de savoir quel jeu d’assets charger sans dépendre d’une variable d’environnement PHP parfois mal transmise :
{
"scripts": {
"dev": "touch .vite-dev && vite",
"build": "rm -f .vite-dev && vite build"
}
}
Ainsi, npm run dev active automatiquement le mode développement côté PHP, et npm run build le désactive avant de générer les fichiers optimisés pour la production.
Servir le style en développement
Un piège fréquent : en développement, Vite injecte le CSS directement via JavaScript (pour permettre le remplacement à chaud sans rechargement complet de la page), plutôt que de charger une feuille de style séparée. Un développeur qui s’attend à voir une balise <link rel="stylesheet"> dans le code source peut croire à tort que le style ne charge pas, alors qu’il est bien appliqué, simplement par un autre mécanisme.
Résultat concret
| Action | webpack (configuration testée) | Vite |
|---|---|---|
| Démarrage du serveur de dev | ~3 s | ~200 ms |
| Rechargement après modification CSS | ~1,5 s | <100 ms |
| Rechargement après modification JS | ~2 s | <150 ms |
En résumé
L’intégration de Vite dans un thème WordPress classique demande un peu de plomberie manuelle — il n’existe pas d’équivalent officiel à @wordpress/scripts pour ce cas d’usage — mais le gain en confort de développement quotidien justifie largement cet investissement initial. Une fois le manifeste correctement lu côté PHP, la bascule entre développement et production devient totalement transparente pour le reste de l’équipe.
