# Sage 10 et Vite : notre migration depuis Laravel Mix pour un thème client

> « JavaScript heap out of memory » sur un build Laravel Mix trop lourd : le récit d'une migration vers Vite sur un thème Sage 10 déjà en production.

- Auteur : WordPress Développement
- Publié le : 2022-06-08
- Mis à jour le : 2022-06-08
- Catégorie : Outils & workflow
- URL : https://www.wpmoderne.fr/outils/sage-10-vite-migration-laravel-mix/

## L’essentiel

- Configuration Vite écrite à la main en remplacement du webpack.mix.js existant
- Alias de chemins à reconfigurer pour retrouver les imports du thème
- Gain de plusieurs secondes sur chaque rechargement pendant le développement

« FATAL ERROR: JavaScript heap out of memory » : ce message, apparu un vendredi après-midi sur le build de production d'un thème Sage 10, a fini de convaincre l'équipe qu'il fallait sortir de Laravel Mix. Le thème avait grossi au fil des mois — plusieurs modules ACF Flexible Content, une bibliothèque de composants JavaScript de plus en plus fournie — et le webpack sous-jacent à Laravel Mix ne suivait plus sans qu'on augmente la mémoire allouée à Node à chaque build.

Le thème tournait déjà en production chez un client depuis un an et demi. Migrer l'outil de build sur un projet actif, sans interrompre les mises en ligne prévues, demandait une approche prudente : remplacer `webpack.mix.js` par une configuration Vite équivalente, sans changer la structure du thème ni ses conventions internes.

## Pourquoi Laravel Mix avait atteint ses limites

Laravel Mix, qui s'appuie sur webpack, recompile l'intégralité du graphe de dépendances à chaque changement de fichier tant que le rechargement à chaud n'est pas parfaitement configuré. Sur ce thème, un simple changement de couleur dans une feuille de style Sass déclenchait un rebuild complet de six à neuf secondes, un délai qui casse la concentration sur une session de développement de plusieurs heures.

Vite, de son côté, s'appuie sur les modules ES natifs du navigateur en développement et ne recompile que le fichier modifié, ce qui ramène ce même rechargement à moins de deux secondes sur le thème une fois la migration terminée.

## Reconstruire la configuration à la main

Aucun outil de migration automatique n'existait pour ce cas précis : la configuration Vite a été écrite entièrement à la main, en s'appuyant sur les points d'entrée déjà définis dans `webpack.mix.js`. Le fichier `vite.config.js` reprend la même logique d'entrées multiples (un point d'entrée pour l'éditeur de blocs, un pour le thème public) que celle qu'utilisait Laravel Mix.

```
import { defineConfig } from 'vite';
import { resolve } from 'path';

export default defineConfig({
  base: '/wp-content/themes/mon-theme/public/',
  build: {
    manifest: true,
    outDir: 'public',
    rollupOptions: {
      input: {
        app: resolve(__dirname, 'resources/js/app.js'),
        editor: resolve(__dirname, 'resources/js/editor.js'),
      },
    },
  },
  resolve: {
    alias: {
      '@scripts': resolve(__dirname, 'resources/js'),
      '@styles': resolve(__dirname, 'resources/css'),
    },
  },
});
```

> L'essentiel à retenir : Configuration Vite écrite à la main en remplacement du webpack.mix.js existant ; Alias de chemins à reconfigurer pour retrouver les imports du thème ; Gain de plusieurs secondes sur chaque rechargement pendant le développement

## Retrouver le manifeste côté PHP

Laravel Mix génère un fichier `mix-manifest.json` que le thème consultait via une fonction utilitaire pour charger les bons fichiers versionnés. Vite génère de son côté un fichier `manifest.json` dans le dossier de sortie, avec une structure légèrement différente : chaque point d'entrée y référence son fichier compilé et ses dépendances CSS associées. La fonction d'enqueue du thème a dû être réécrite pour lire ce nouveau format et appeler correctement `wp_enqueue_script()` et `wp_enqueue_style()` avec les chemins générés.

## Les alias de chemins, le vrai point de friction

Les imports du thème utilisaient des alias de chemins définis dans `webpack.mix.js` (comme `@scripts` et `@styles`) dans plus de quarante fichiers JavaScript et Sass. Chaque alias a dû être redéclaré dans la section `resolve.alias` de Vite avec une syntaxe légèrement différente, sous peine d'erreurs d'import silencieuses qui n'apparaissaient qu'à l'exécution dans le navigateur plutôt qu'au moment du build.

- Recensement de tous les alias utilisés dans le thème avant migration
- Redéclaration un par un dans `vite.config.js`
- Vérification systématique de chaque page du site après la bascule

## Le mode développement en parallèle de la production

Pendant la phase de test, les deux configurations de build ont coexisté quelques semaines : Laravel Mix restait disponible pour reconstruire les assets de production en cas de problème urgent, pendant que Vite servait exclusivement l'environnement de développement local. Cette coexistence temporaire a rassuré l'équipe avant de retirer complètement Laravel Mix du projet.

> Ne jamais retirer l'ancien outil de build tant que le nouveau n'a pas tourné sur au moins une mise en production réelle : le filet de sécurité coûte peu et évite un blocage un jour de déploiement urgent.

## Notre verdict

Le gain de rechargement en développement (moins de deux secondes contre six à neuf) a largement justifié le temps investi dans la migration, environ trois jours pleins pour reconstruire la configuration et vérifier chaque page du thème. La bascule vers Vite du reste de Sage 10 lui-même, en tant que projet, n'était pas encore d'actualité à ce moment : ce chantier ne concernait que le thème de ce client précis, migré indépendamment de toute évolution officielle de Sage.