Como Verificar a Versão do Webpack: Terminal, package.json e Config

As cinco versões principais do webpack não são substitutas diretas umas das outras. Cada versão principal introduziu mudanças que quebram a sintaxe de configuração, a compatibilidade de loaders e as APIs de plugins. Uma config do webpack 4 não funcionará com o webpack 5 sem modificações, e loaders publicados para o webpack 3 podem falhar silenciosamente ou produzir saída incorreta no webpack 4+.

Além da compatibilidade de configuração, a versão do webpack afeta o desempenho. O webpack 5 introduziu cache persistente, Module Federation e tree-shaking aprimorado que podem reduzir significativamente os tempos de build e os tamanhos de bundle em comparação ao webpack 4. Se você está depurando um build lento ou investigando uma regressão no tamanho do bundle, confirmar a versão é o primeiro passo de diagnóstico.

Quando conflitos de versão causam erros

• Incompatibilidade de loaders - o `babel-loader` v8 mira o webpack 4; usá-lo com o webpack 5 sem atualizar causa configuração incorreta silenciosa.
• Divergências na API de plugins - plugins que se conectam ao compilador do webpack usam uma API que mudou entre a v4 e a v5. Um plugin feito para a v4 falhará em um objeto compilador da v5.
• Conflitos de peer dependencies - ferramentas como `webpack-dev-server`, `html-webpack-plugin` e `mini-css-extract-plugin` publicam versões atreladas a versões principais específicas do webpack.
• Erros de schema do css-loader - o css-loader v5 e v6 têm validação de schema estrita; uma incompatibilidade de versão com o webpack produz o erro "ValidationError: Invalid options object".

O terminal é a forma mais rápida e confiável de verificar sua versão do webpack. Há três comandos que valem a pena conhecer, cada um adequado a uma situação ligeiramente diferente.

O webpack é instalado localmente no seu projeto como devDependency. A versão instalada globalmente, se houver, quase nunca é a que o seu build realmente usa.

A versão local do projeto (a mais confiável)

Seu projeto quase certamente instala o webpack como devDependency local, não como pacote global. Para verificar a versão que seus scripts de build realmente usam, execute `npx` ou `./node_modules/.bin/webpack` diretamente da raiz do projeto. Esses comandos ignoram qualquer instalação global do webpack e reportam a versão instalada localmente.

# A mais confiável - usa a instalação local do node_modules
npx webpack --version

# Invocação alternativa por caminho
./node_modules/.bin/webpack --version

# Usando yarn
yarn webpack --version

# Pnpm
pnpm exec webpack --version

O comando npm list

`npm list webpack` consulta os seus `node_modules` locais e imprime a versão instalada junto com sua posição na árvore de dependências. Isso é útil quando você quer ver não apenas a versão, mas também qual pacote exigiu o webpack como peer dependency — uma fonte comum de conflitos de versão quando uma ferramenta de build depende de uma faixa específica do webpack.

# Mostrar a versão do webpack no node_modules local
npm list webpack

# Mostrar todos os pacotes da árvore que dependem do webpack
npm list webpack --all

# Equivalente no yarn
yarn list --pattern webpack

# Equivalente no pnpm
pnpm list webpack

A versão instalada globalmente

Se você instalou o webpack globalmente com `npm install -g webpack webpack-cli`, pode verificar essa versão separadamente. Esteja ciente de que a versão global raramente é a que os builds do seu projeto usam — a maioria dos scripts de build invoca o webpack por meio dos scripts do `package.json`, que sempre resolvem para a instalação local.

# Verificação da instalação global
webpack --version

# Ou explicitamente do caminho global
npm list -g webpack

O arquivo `package.json` do seu projeto lista a faixa de versões do webpack que o seu projeto declarou como dependência. Não é o mesmo que a versão instalada — é a faixa especificada quando o webpack foi adicionado, e a versão realmente instalada pode ser qualquer versão dentro dessa faixa.

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

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

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

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

Às vezes você precisa saber a versão do webpack em tempo de build — por exemplo, para aplicar um ramo de configuração diferente conforme a versão principal, ou para registrar informações de diagnóstico em um pipeline de CI. O webpack expõe sua versão como uma propriedade no objeto compilador, e o próprio pacote webpack exporta uma string `version`.

Lendo a versão no webpack.config.js

const webpack = require('webpack');

// A string de versão está disponível diretamente
console.log('Webpack version:', webpack.version);

// Use-a para aplicar configuração condicionalmente
const isWebpack5 = parseInt(webpack.version, 10) >= 5;

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

Lendo a versão em um plugin ou loader personalizado

Dentro de um plugin do webpack, o objeto compilador carrega a versão do webpack via `compiler.webpack.version`. Esta é a verificação programática mais segura porque lê a versão da instância do webpack que invocou o plugin — não a que por acaso estiver instalada no `node_modules`.

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

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

Verificando a versão em um ambiente de CI

Em um pipeline de CI, a maneira mais limpa de registrar a versão do webpack é adicionar uma etapa que execute `npx webpack --version` e capture a saída. Isso fornece a versão instalada localmente dos `node_modules` exatos que o build usará, e ela aparece no log do pipeline em cada execução — útil para depurar falhas de build que só aparecem em certos 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 as diferenças entre as versões principais do webpack ajuda você a decidir se a sua versão atual é adequada ao seu projeto e o que esperar se migrar. Aqui está uma comparação concisa das capacidades e do cenário de compatibilidade de todas as cinco versões principais.

Webpack 4 vs webpack 5 - diferenças principais

• Cache persistente - o webpack 5 armazena em cache os resultados da compilação em disco entre execuções; um cache quente pode tornar os rebuilds de 5 a 10 vezes mais rápidos que o webpack 4.
• Module Federation - o webpack 5 introduziu a Module Federation para compartilhar código entre frontends implantados de forma independente em tempo de execução.
• Módulos de assets - o webpack 5 substitui `file-loader`, `url-loader` e `raw-loader` por tipos de módulos de asset integrados (`asset/resource`, `asset/inline`, etc.).
• Polyfills do Node.js removidos - o webpack 5 não preenche mais automaticamente os módulos core do Node.js. Projetos que dependiam de polyfills para `buffer`, `path`, `stream`, etc. devem adicioná-los explicitamente.
• Cache de longo prazo - o webpack 5 usa IDs de chunk determinísticos por padrão, produzindo nomes de arquivo estáveis entre builds que melhoram as taxas de acerto do cache do navegador.

Conflitos de versão entre o webpack e seu ecossistema são a fonte mais comum de erros de build confusos. A maioria desses erros remonta a uma de três causas raiz: múltiplas cópias do webpack no `node_modules`, um loader ou plugin feito para uma versão principal diferente, ou uma incompatibilidade na faixa de peer dependency.

Múltiplas cópias do webpack no node_modules

É possível — e surpreendentemente comum — ter mais de uma cópia do webpack instalada no seu projeto. Isso acontece quando uma dependência declara uma peer dependency do webpack com uma faixa de versão principal diferente da que o seu projeto usa. O resultado são duas instâncias incompatíveis do webpack, o que faz com que os plugins falhem silenciosamente ou travem porque estão registrados em uma instância mas invocados por outra.

# Verificar múltiplas entradas de webpack na árvore completa de dependências
npm list webpack --all

# Procurar mais de um número de versão único na saída
# p. ex., aparecer tanto [email protected] quanto [email protected]
# é sinal de peer dependencies em conflito

Resolvendo conflitos de peer dependencies

Quando o `npm list webpack --all` mostra múltiplas versões do webpack, veja qual pacote está puxando a versão mais antiga. Atualize esse pacote para uma versão que suporte sua versão principal do webpack, ou use o campo `resolutions` (Yarn) ou `overrides` (npm 8+) para forçar todos os pacotes a usarem uma única versão do webpack.

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

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

Validando faixas semver

Faixas de peer dependency como `"webpack": "^4 || ^5"` e `"webpack": ">=4.41.0 <6"` são expressões semver válidas, mas fáceis de interpretar mal. O validador de semver da Aback Tools verifica qualquer string de versão ou expressão de faixa contra a especificação Semver 2.0.0 — útil quando você está escrevendo uma biblioteca que declara uma faixa de peer dependency do webpack e quer confirmar que a expressão está corretamente formada.

Conhecer sua versão atual do webpack é só o começo. Gerenciá-la bem — para que a versão permaneça consistente entre ambientes, seja visível para cada contribuidor e seja atualizada deliberadamente e não por acidente — exige algumas práticas simples.

1. Fixe versões exatas nas devDependencies - use `"webpack": "5.88.2"` em vez de `"^5.88.0"` para ferramentas críticas ao build. Faixas flutuantes permitem que patches mudem a versão instalada entre execuções de `npm install` em máquinas diferentes, tornando a saída do build não determinística.
2. Faça commit do seu lock file - `package-lock.json`, `yarn.lock` ou `pnpm-lock.yaml` devem estar no controle de versão. Sem ele, contribuidores e servidores de CI instalam versões de patch diferentes.
3. Registre a versão no CI - adicione uma etapa `npx webpack --version` antes de cada job de build. A versão aparece em todos os logs de CI, facilitando correlacionar falhas de build com mudanças de versão.
4. Audite as dependências após atualizações - quando você atualizar o webpack, execute imediatamente `npm list webpack --all` para confirmar que nenhuma cópia secundária entrou, e `npx webpack --version` para confirmar que a nova versão é a que o seu build está usando.
5. Leia o guia de migração antes de atualizar - cada versão principal do webpack tem um guia de migração oficial em `webpack.js.org`. Leia-o antes de atualizar — não depois que o build quebrar.