Cómo Comprobar la Versión de Webpack: Terminal, package.json y Config

Las cinco versiones principales de webpack no son reemplazos directos entre sí. Cada versión principal introdujo cambios rompientes en la sintaxis de configuración, la compatibilidad de loaders y las APIs de plugins. Una config de webpack 4 no funcionará con webpack 5 sin modificaciones, y los loaders publicados para webpack 3 pueden fallar silenciosamente o producir una salida incorrecta en webpack 4+.

Más allá de la compatibilidad de configuración, la versión de webpack afecta al rendimiento. Webpack 5 introdujo caché persistente, Module Federation y un tree-shaking mejorado que puede reducir significativamente los tiempos de build y los tamaños de bundle en comparación con webpack 4. Si estás depurando un build lento o investigando una regresión en el tamaño del bundle, confirmar la versión es el primer paso de diagnóstico.

Cuando los conflictos de versión causan errores

• Incompatibilidad de loaders - `babel-loader` v8 apunta a webpack 4; usarlo con webpack 5 sin actualizar causa una mala configuración silenciosa.
• Desajustes de la API de plugins - los plugins que se enganchan al compilador de webpack usan una API que cambió entre la v4 y la v5. Un plugin construido para v4 fallará sobre un objeto compilador de v5.
• Conflictos de peer dependencies - herramientas como `webpack-dev-server`, `html-webpack-plugin` y `mini-css-extract-plugin` publican versiones ligadas a versiones principales específicas de webpack.
• Errores de esquema de css-loader - css-loader v5 y v6 tienen validación de esquema estricta; un desajuste de versión con webpack produce el error "ValidationError: Invalid options object".

La terminal es la forma más rápida y fiable de comprobar tu versión de webpack. Hay tres comandos que vale la pena conocer, cada uno adecuado para una situación ligeramente diferente.

Webpack se instala localmente en tu proyecto como devDependency. La versión instalada globalmente, si existe, casi nunca es la que tu build está usando realmente.

La versión local del proyecto (la más fiable)

Tu proyecto casi con seguridad instala webpack como devDependency local, no como paquete global. Para comprobar la versión que tus scripts de build usan realmente, ejecuta `npx` o `./node_modules/.bin/webpack` directamente desde la raíz del proyecto. Estos comandos omiten cualquier instalación global de webpack y reportan la versión instalada localmente.

# La más fiable - usa la instalación local de node_modules
npx webpack --version

# Invocación alternativa por ruta
./node_modules/.bin/webpack --version

# Con yarn
yarn webpack --version

# Pnpm
pnpm exec webpack --version

El comando npm list

`npm list webpack` consulta tus `node_modules` locales e imprime la versión instalada junto con su posición en el árbol de dependencias. Es útil cuando quieres ver no solo la versión sino también qué paquete requirió webpack como peer dependency — una fuente habitual de conflictos de versiones cuando una herramienta de build depende de un rango específico de webpack.

# Mostrar la versión de webpack en node_modules local
npm list webpack

# Mostrar todos los paquetes del árbol que dependen de webpack
npm list webpack --all

# Equivalente en yarn
yarn list --pattern webpack

# Equivalente en pnpm
pnpm list webpack

La versión instalada globalmente

Si instalaste webpack globalmente con `npm install -g webpack webpack-cli`, puedes comprobar esa versión por separado. Ten en cuenta que la versión global rara vez es la que usan los builds de tu proyecto — la mayoría de los scripts de build invocan webpack a través de los scripts de `package.json`, que siempre resuelven a la instalación local.

# Verificación de instalación global
webpack --version

# O explícitamente desde la ruta global
npm list -g webpack

El archivo `package.json` de tu proyecto lista el rango de versiones de webpack que tu proyecto declaró como dependencia. No es lo mismo que la versión instalada — es el rango que se especificó cuando se añadió webpack, y la versión realmente instalada puede ser cualquier versión dentro de ese rango.

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

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

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

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

A veces necesitas saber la versión de webpack en tiempo de build — por ejemplo, para aplicar una rama de configuración diferente según la versión principal, o para registrar información de diagnóstico en un pipeline de CI. Webpack expone su versión como una propiedad del objeto compilador, y el propio paquete webpack exporta una cadena `version`.

Leer la versión en webpack.config.js

const webpack = require('webpack');

// La cadena de versión está disponible directamente
console.log('Webpack version:', webpack.version);

// Úsala para aplicar configuración condicionalmente
const isWebpack5 = parseInt(webpack.version, 10) >= 5;

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

Leer la versión en un plugin o loader personalizado

Dentro de un plugin de webpack, el objeto compilador lleva la versión de webpack vía `compiler.webpack.version`. Esta es la comprobación programática más segura porque lee la versión de la instancia de webpack que invocó al plugin — no la versión que casualmente esté instalada en `node_modules`.

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

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

Comprobar la versión en un entorno de CI

En un pipeline de CI, la forma más limpia de registrar la versión de webpack es añadir un paso que ejecute `npx webpack --version` y capture la salida. Esto te da la versión instalada localmente de los `node_modules` exactos que usará el build, y aparece en el log del pipeline en cada ejecución — útil para depurar fallos de build que solo aparecen en ciertos 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

Entender las diferencias entre las versiones principales de webpack te ayuda a decidir si tu versión actual es adecuada para tu proyecto y qué esperar si migras. Aquí tienes una comparación concisa de las capacidades y el panorama de compatibilidad de las cinco versiones principales.

Webpack 4 vs webpack 5 - diferencias clave

• Caché persistente - webpack 5 cachea los resultados de compilación en disco entre ejecuciones; una caché caliente puede hacer los rebuilds entre 5 y 10 veces más rápidos que webpack 4.
• Module Federation - webpack 5 introdujo Module Federation para compartir código entre frontends desplegados independientemente en tiempo de ejecución.
• Módulos de assets - webpack 5 reemplaza `file-loader`, `url-loader` y `raw-loader` con tipos de módulos de asset integrados (`asset/resource`, `asset/inline`, etc.).
• Polyfills de Node.js eliminados - webpack 5 ya no rellena automáticamente los módulos core de Node.js. Los proyectos que dependían de polyfills para `buffer`, `path`, `stream`, etc. deben añadirlos explícitamente.
• Caché a largo plazo - webpack 5 usa IDs de chunk deterministas por defecto, produciendo nombres de archivo estables entre builds que mejoran las tasas de acierto de la caché del navegador.

Los conflictos de versiones entre webpack y su ecosistema son la fuente más común de errores de build confusos. La mayoría de estos errores se remontan a una de tres causas raíz: múltiples copias de webpack en `node_modules`, un loader o plugin construido para una versión principal diferente, o un desajuste en el rango de peer dependencies.

Múltiples copias de webpack en node_modules

Es posible — y sorprendentemente común — tener más de una copia de webpack instalada en tu proyecto. Esto ocurre cuando una dependencia declara una peer dependency sobre webpack con un rango de versión principal diferente al que usa tu proyecto. El resultado son dos instancias de webpack incompatibles, lo que hace que los plugins fallen silenciosamente o se bloqueen porque están registrados contra una instancia pero invocados por otra.

# Comprobar múltiples entradas de webpack en el árbol completo de dependencias
npm list webpack --all

# Buscar más de un número de versión único en la salida
# p. ej., que aparezcan tanto [email protected] como [email protected]
# es señal de peer dependencies en conflicto

Resolver conflictos de peer dependencies

Cuando `npm list webpack --all` muestra múltiples versiones de webpack, mira qué paquete está arrastrando la versión antigua. Actualiza ese paquete a una versión que soporte tu versión principal de webpack, o usa el campo `resolutions` (Yarn) o `overrides` (npm 8+) para forzar que todos los paquetes usen una única versión de webpack.

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

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

Validar rangos semver

Rangos de peer dependencies como `"webpack": "^4 || ^5"` y `"webpack": ">=4.41.0 <6"` son expresiones semver válidas pero fáciles de malinterpretar. El validador de semver de Aback Tools comprueba cualquier cadena de versión o expresión de rango contra la especificación Semver 2.0.0 — útil cuando escribes una librería que declara un rango de peer dependency de webpack y quieres confirmar que la expresión está bien formada.

Conocer tu versión actual de webpack es solo el comienzo. Gestionarla bien — de modo que la versión se mantenga consistente entre entornos, sea visible para cada colaborador y se actualice deliberadamente y no por accidente — requiere unas prácticas sencillas.

1. Fija versiones exactas en devDependencies - usa `"webpack": "5.88.2"` en lugar de `"^5.88.0"` para herramientas críticas del build. Los rangos flotantes permiten que los parches cambien la versión instalada entre ejecuciones de `npm install` en distintas máquinas, haciendo la salida del build no determinista.
2. Haz commit de tu lock file - `package-lock.json`, `yarn.lock` o `pnpm-lock.yaml` deben estar en el control de versiones. Sin él, los colaboradores y servidores de CI instalan versiones de parche diferentes.
3. Registra la versión en CI - añade un paso `npx webpack --version` antes de cada job de build. La versión aparece en cada log de CI, facilitando correlacionar fallos de build con cambios de versión.
4. Audita las dependencias tras las actualizaciones - cuando actualices webpack, ejecuta de inmediato `npm list webpack --all` para confirmar que no se colaron copias secundarias, y `npx webpack --version` para confirmar que la nueva versión es la que usa tu build.
5. Lee la guía de migración antes de actualizar - cada versión principal de webpack tiene una guía de migración oficial en `webpack.js.org`. Léela antes de actualizar — no después de que el build se rompa.