Comment Vérifier la Version de Webpack : Terminal, package.json et Config

Les cinq versions majeures de webpack ne sont pas des remplacements directs les unes des autres. Chaque version majeure a introduit des changements cassants dans la syntaxe de configuration, la compatibilité des loaders et les API de plugins. Une config webpack 4 ne fonctionnera pas avec webpack 5 sans modifications, et les loaders publiés pour webpack 3 peuvent échouer silencieusement ou produire une sortie incorrecte avec webpack 4+.

Au-delà de la compatibilité de configuration, la version de webpack affecte les performances. Webpack 5 a introduit la mise en cache persistante, la Module Federation et un tree-shaking amélioré qui peuvent réduire considérablement les temps de build et les tailles de bundle par rapport à webpack 4. Si vous déboguez un build lent ou enquêtez sur une régression de taille de bundle, confirmer la version est la première étape de diagnostic.

Quand les conflits de versions provoquent des erreurs

• Incompatibilité de loaders - `babel-loader` v8 cible webpack 4 ; l'utiliser avec webpack 5 sans mise à jour provoque une mauvaise configuration silencieuse.
• Divergences d'API de plugins - les plugins qui se greffent au compilateur webpack utilisent une API qui a changé entre la v4 et la v5. Un plugin conçu pour la v4 échouera sur un objet compilateur v5.
• Conflits de peer dependencies - des outils comme `webpack-dev-server`, `html-webpack-plugin` et `mini-css-extract-plugin` publient des versions liées à des versions majeures spécifiques de webpack.
• Erreurs de schéma de css-loader - css-loader v5 et v6 ont une validation de schéma stricte ; un écart de version avec webpack produit l'erreur « ValidationError: Invalid options object ».

Le terminal est le moyen le plus rapide et le plus fiable de vérifier votre version de webpack. Trois commandes méritent d'être connues, chacune adaptée à une situation légèrement différente.

Webpack est installé localement dans votre projet comme devDependency. La version installée globalement, s'il y en a une, n'est presque jamais celle que votre build utilise réellement.

La version locale du projet (la plus fiable)

Votre projet installe presque certainement webpack comme devDependency locale, pas comme paquet global. Pour vérifier la version que vos scripts de build utilisent réellement, exécutez `npx` ou `./node_modules/.bin/webpack` directement depuis la racine du projet. Ces commandes contournent toute installation globale de webpack et rapportent la version installée localement.

# La plus fiable - utilise l'installation locale de node_modules
npx webpack --version

# Invocation alternative par chemin
./node_modules/.bin/webpack --version

# Avec yarn
yarn webpack --version

# Pnpm
pnpm exec webpack --version

La commande npm list

`npm list webpack` interroge vos `node_modules` locaux et affiche la version installée avec sa position dans l'arbre de dépendances. C'est utile quand vous voulez voir non seulement la version mais aussi quel paquet a exigé webpack comme peer dependency — une source courante de conflits de versions quand un outil de build dépend d'une plage spécifique de webpack.

# Afficher la version de webpack dans node_modules local
npm list webpack

# Afficher tous les paquets de l'arbre qui dépendent de webpack
npm list webpack --all

# Équivalent yarn
yarn list --pattern webpack

# Équivalent pnpm
pnpm list webpack

La version installée globalement

Si vous avez installé webpack globalement avec `npm install -g webpack webpack-cli`, vous pouvez vérifier cette version séparément. Sachez que la version globale est rarement celle utilisée par les builds de votre projet — la plupart des scripts de build invoquent webpack via les scripts de `package.json`, qui résolvent toujours vers l'installation locale.

# Vérification de l'installation globale
webpack --version

# Ou explicitement depuis le chemin global
npm list -g webpack

Le fichier `package.json` de votre projet liste la plage de versions de webpack déclarée comme dépendance. Ce n'est pas la même chose que la version installée — c'est la plage spécifiée quand webpack a été ajouté, et la version réellement installée peut être n'importe quelle version de cette plage.

{
  "devDependencies": {
    "webpack": "^5.88.0",
    "webpack-cli": "^5.1.4",
    "webpack-dev-server": "^4.15.1"
  }
}

# Dans package-lock.json (npm)
grep '"webpack"' package-lock.json | head -5

# Dans yarn.lock
grep 'webpack@' yarn.lock | head -5

# Dans pnpm-lock.yaml
grep 'webpack' pnpm-lock.yaml | head -10

Parfois, vous devez connaître la version de webpack au moment du build — par exemple pour appliquer une branche de configuration différente selon la version majeure, ou pour consigner des informations de diagnostic dans un pipeline CI. Webpack expose sa version comme propriété de l'objet compilateur, et le paquet webpack lui-même exporte une chaîne `version`.

Lire la version dans webpack.config.js

const webpack = require('webpack');

// La chaîne de version est disponible directement
console.log('Webpack version:', webpack.version);

// Utilisez-la pour appliquer la configuration conditionnellement
const isWebpack5 = parseInt(webpack.version, 10) >= 5;

module.exports = {
  // ...
  plugins: [
    isWebpack5
      ? new webpack.ids.DeterministicModuleIdsPlugin()
      : new webpack.HashedModuleIdsPlugin(),
  ],
};

Lire la version dans un plugin ou un loader personnalisé

Dans un plugin webpack, l'objet compilateur porte la version de webpack via `compiler.webpack.version`. C'est la vérification programmatique la plus sûre car elle lit la version de l'instance de webpack qui a invoqué le plugin — pas celle qui se trouve par hasard dans `node_modules`.

class MyPlugin {
  apply(compiler) {
    // compiler.webpack est disponible dans webpack 5+
    const version = compiler.webpack?.version ?? webpack.version;
    console.log('Running on webpack', version);

    compiler.hooks.done.tap('MyPlugin', (stats) => {
      // Build complete
    });
  }
}

Vérifier la version dans un environnement CI

Dans un pipeline CI, la façon la plus propre de consigner la version de webpack est d'ajouter une étape qui exécute `npx webpack --version` et capture la sortie. Cela vous donne la version installée localement depuis les `node_modules` exacts que le build utilisera, et elle apparaît dans le journal du pipeline à chaque exécution — utile pour déboguer des échecs de build qui n'apparaissent que sur certains runners.

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
  - run: npm ci
  - name: Log webpack version
    run: npx webpack --version
  - name: Build
    run: npm run build

Comprendre les différences entre les versions majeures de webpack vous aide à décider si votre version actuelle convient à votre projet et à quoi vous attendre si vous migrez. Voici une comparaison concise des capacités et du paysage de compatibilité des cinq versions majeures.

Webpack 4 vs webpack 5 - différences clés

• Cache persistant - webpack 5 met en cache les résultats de compilation sur disque entre les exécutions ; un cache chaud peut rendre les rebuilds 5 à 10 fois plus rapides qu'avec webpack 4.
• Module Federation - webpack 5 a introduit la Module Federation pour partager du code entre des frontends déployés indépendamment à l'exécution.
• Modules d'assets - webpack 5 remplace `file-loader`, `url-loader` et `raw-loader` par des types de modules d'assets intégrés (`asset/resource`, `asset/inline`, etc.).
• Polyfills Node.js supprimés - webpack 5 ne polyfill plus automatiquement les modules core de Node.js. Les projets qui dépendaient de polyfills pour `buffer`, `path`, `stream`, etc. doivent les ajouter explicitement.
• Cache à long terme - webpack 5 utilise des IDs de chunks déterministes par défaut, produisant des noms de fichiers stables entre les builds qui améliorent les taux d'accès au cache du navigateur.

Les conflits de versions entre webpack et son écosystème sont la source la plus courante d'erreurs de build déroutantes. La plupart de ces erreurs remontent à l'une de trois causes racines : plusieurs copies de webpack dans `node_modules`, un loader ou plugin conçu pour une version majeure différente, ou un écart de plage de peer dependency.

Plusieurs copies de webpack dans node_modules

C'est possible — et étonnamment courant — d'avoir plus d'une copie de webpack installée dans votre projet. Cela arrive quand une dépendance déclare une peer dependency sur webpack avec une plage de version majeure différente de celle de votre projet. Le résultat est deux instances de webpack incompatibles, ce qui fait que les plugins échouent silencieusement ou plantent parce qu'ils sont enregistrés auprès d'une instance mais invoqués par une autre.

# Vérifier les multiples entrées webpack dans l'arbre complet des dépendances
npm list webpack --all

# Chercher plus d'un numéro de version unique dans la sortie
# p. ex., voir apparaître à la fois [email protected] et [email protected]
# est un signe de peer dependencies en conflit

Résoudre les conflits de peer dependencies

Quand `npm list webpack --all` montre plusieurs versions de webpack, regardez quel paquet tire l'ancienne version. Mettez ce paquet à jour vers une version qui prend en charge votre version majeure de webpack, ou utilisez le champ `resolutions` (Yarn) ou `overrides` (npm 8+) pour forcer tous les paquets à utiliser une seule version de webpack.

{
  "overrides": {
    "webpack": "^5.88.0"
  }
}

{
  "resolutions": {
    "webpack": "^5.88.0"
  }
}

Valider les plages semver

Les plages de peer dependencies comme `"webpack": "^4 || ^5"` et `"webpack": ">=4.41.0 <6"` sont des expressions semver valides mais faciles à mal lire. Le validateur semver d'Aback Tools vérifie toute chaîne de version ou expression de plage contre la spécification Semver 2.0.0 — utile quand vous écrivez une bibliothèque qui déclare une plage de peer dependency webpack et voulez confirmer que l'expression est correctement formée.

Connaître votre version actuelle de webpack n'est que le début. Bien la gérer — pour que la version reste cohérente entre les environnements, soit visible de chaque contributeur et soit mise à jour délibérément plutôt qu'accidentellement — exige quelques pratiques simples.

1. Figez les versions exactes dans devDependencies - utilisez `"webpack": "5.88.2"` plutôt que `"^5.88.0"` pour les outils critiques du build. Les plages flottantes permettent aux correctifs de changer la version installée entre les exécutions de `npm install` sur différentes machines, rendant la sortie du build non déterministe.
2. Commitez votre fichier de verrouillage - `package-lock.json`, `yarn.lock` ou `pnpm-lock.yaml` doivent être commités dans le contrôle de version. Sans lui, les contributeurs et serveurs CI installent des versions de correctif différentes.
3. Consignez la version en CI - ajoutez une étape `npx webpack --version` avant chaque job de build. La version apparaît dans chaque journal CI, facilitant la corrélation entre échecs de build et changements de version.
4. Auditez les dépendances après les mises à niveau - quand vous mettez à jour webpack, exécutez immédiatement `npm list webpack --all` pour confirmer qu'aucune copie secondaire ne s'est glissée, et `npx webpack --version` pour confirmer que la nouvelle version est bien celle utilisée par votre build.
5. Lisez le guide de migration avant de mettre à niveau - chaque version majeure de webpack a un guide de migration officiel sur `webpack.js.org`. Lisez-le avant de mettre à niveau — pas après que le build a cassé.