webpack и webpack-cli: разница и взаимодействие

В экосистеме Webpack существует два базовых пакета:

  • webpack
  • webpack-cli

Несмотря на тесную связь, они решают разные задачи и работают на разных уровнях архитектуры сборщика.

Пакет webpack

Пакет webpack содержит:

  • ядро сборщика;
  • механизм анализа модулей;
  • систему зависимостей;
  • обработку графа импортов;
  • инфраструктуру loader’ов и plugin’ов;
  • алгоритмы оптимизации;
  • внутренний API;
  • runtime-систему.

Именно webpack выполняет:

  • чтение входных файлов;
  • построение dependency graph;
  • трансформацию модулей;
  • генерацию bundle-файлов;
  • tree shaking;
  • code splitting;
  • chunk generation;
  • оптимизацию production-сборок.

Без пакета webpack сама система сборки не существует.

Пакет webpack-cli

Пакет webpack-cli представляет собой интерфейс командной строки для управления ядром Webpack.

Он обеспечивает:

  • запуск сборки через терминал;
  • обработку CLI-аргументов;
  • работу команд build, serve, watch;
  • загрузку конфигурации;
  • взаимодействие с пользователем;
  • генерацию шаблонов проектов;
  • интеграцию с dev-средой.

webpack-cli не выполняет сборку самостоятельно. Он лишь управляет ядром webpack.

Архитектурное разделение

Разделение на webpack и webpack-cli основано на принципе разделения ответственности.

webpack отвечает за:

Область Описание
Компиляция Преобразование модулей
Dependency Graph Построение графа зависимостей
Chunk System Формирование чанков
Optimization Оптимизация сборки
Plugin API Подключение расширений
Loader Pipeline Обработка файлов

webpack-cli отвечает за:

Область Описание
Командная строка Работа с terminal-командами
Аргументы Парсинг CLI-параметров
Конфигурация Загрузка webpack.config.js
Dev Workflow Watch mode и dev server
UX Взаимодействие с пользователем
Инициализация Генерация проектов

Почему пакеты разделены

Исторически Webpack развивался как инструмент с большим количеством сценариев использования:

  • CLI;
  • Node.js API;
  • серверные интеграции;
  • кастомные build-системы;
  • CI/CD;
  • IDE-интеграции.

Если бы CLI был встроен непосредственно в ядро:

  • увеличивался бы размер пакета;
  • усложнялась поддержка;
  • возрастала связанность модулей;
  • ухудшалась расширяемость;
  • становилось сложнее использовать Webpack программно.

Разделение позволило:

  • изолировать terminal-логику;
  • сделать ядро более универсальным;
  • упростить обновления CLI;
  • развивать инструменты независимо;
  • уменьшить зависимость между слоями системы.

Установка пакетов

Обычно оба пакета устанавливаются одновременно.

npm

npm install webpack webpack-cli --save-dev

yarn

yarn add webpack webpack-cli -D

pnpm

pnpm add webpack webpack-cli -D

Что произойдёт при установке только webpack

Если установить только ядро:

npm install webpack --save-dev

появится API сборщика, но команды терминала работать не будут.

Например:

npx webpack

может завершиться ошибкой:

CLI for webpack must be installed.
webpack-cli (https://github.com/webpack/webpack-cli)

Причина заключается в том, что ядро не содержит terminal-интерфейс.

Что произойдёт при установке только webpack-cli

Установка только CLI:

npm install webpack-cli --save-dev

не имеет смысла без ядра.

CLI — лишь оболочка над webpack.

При запуске возникнет ошибка отсутствия основного компилятора.

Взаимодействие webpack-cli с ядром

Процесс взаимодействия выглядит следующим образом.

1. Запуск команды

Пользователь выполняет:

npx webpack

или:

npm run build

2. Инициализация webpack-cli

CLI:

  • считывает аргументы;
  • определяет режим работы;
  • ищет конфигурационный файл;
  • анализирует параметры окружения.

3. Загрузка конфигурации

CLI ищет:

webpack.config.js

или альтернативные варианты:

webpack.config.cjs
webpack.config.mjs
webpack.config.ts

4. Создание compiler instance

После чтения конфигурации CLI вызывает API ядра:

const webpack = require('webpack');

const compiler = webpack(config);

На этом этапе начинается работа самого Webpack.

5. Запуск компиляции

CLI инициирует:

compiler.run();

или:

compiler.watch();

6. Получение результата

Ядро Webpack:

  • строит граф зависимостей;
  • запускает loader’ы;
  • применяет plugin’ы;
  • генерирует bundle.

7. Вывод информации

webpack-cli получает результат и выводит:

  • ошибки;
  • warnings;
  • statistics;
  • build time;
  • размер bundle;
  • информацию о чанках.

Работа через Node.js API без webpack-cli

CLI не является обязательным компонентом.

Webpack можно запускать напрямую через Node.js.

Пример

const webpack = require('webpack');
const config = require('./webpack.config');

const compiler = webpack(config);

compiler.run((err, stats) => {
    if (err) {
        console.error(err);
        return;
    }

    console.log(stats.toString());
});

В этом случае:

  • webpack-cli не нужен;
  • управление сборкой полностью программное;
  • появляется возможность создавать собственные build-системы.

Основные команды webpack-cli

Сборка проекта

npx webpack

Production mode

npx webpack --mode production

Development mode

npx webpack --mode development

Watch mode

npx webpack --watch

Указание конфигурации

npx webpack --config webpack.prod.js

Передача environment variables

npx webpack --env production

Просмотр справки

npx webpack --help

Как CLI обрабатывает аргументы

webpack-cli анализирует параметры командной строки и преобразует их в настройки ядра.

Например:

npx webpack --mode production

превращается в:

{
    mode: 'production'
}

Несколько аргументов одновременно

npx webpack --watch --progress --profile

CLI:

  • активирует watch mode;
  • включает отображение прогресса;
  • собирает profiling-информацию.

Роль webpack-cli в dev workflow

CLI значительно упрощает разработку.

Возможности

Возможность Описание
Watch Mode Автоматическая пересборка
Progress Bar Отображение прогресса
Build Stats Статистика сборки
Environment Flags Передача env-переменных
Config Selection Выбор конфигураций
Multi Config Работа с несколькими конфигами

Связь с webpack-dev-server

Ранее webpack-dev-server запускался через отдельные команды, однако современный webpack-cli интегрирован с dev server.

Пример:

npx webpack serve

CLI:

  • запускает dev server;
  • подключает middleware;
  • активирует HMR;
  • управляет live reload.

Разница между API и CLI

CLI-подход

npx webpack

Подходит для:

  • обычных проектов;
  • frontend-разработки;
  • CI/CD;
  • локальной сборки.

API-подход

compiler.run();

Подходит для:

  • кастомных build-систем;
  • IDE;
  • внутренних инструментов;
  • серверной автоматизации;
  • платформенных решений.

Как webpack-cli ищет конфигурацию

По умолчанию используется поиск:

webpack.config.js

Если файл не найден, CLI:

  • пытается использовать встроенные настройки;
  • либо сообщает об ошибке.

Явное указание конфига

npx webpack --config configs/webpack.prod.js

Несколько конфигураций

Webpack поддерживает массив конфигов:

module.exports = [
    clientConfig,
    serverConfig
];

CLI автоматически запускает multiple compilation.

Внутренний lifecycle взаимодействия

Внутренне взаимодействие между CLI и ядром выглядит как последовательность стадий:

CLI START
    ↓
Parse Arguments
    ↓
Load Config
    ↓
Create Compiler
    ↓
Initialize Plugins
    ↓
Build Dependency Graph
    ↓
Apply Loaders
    ↓
Optimize Chunks
    ↓
Emit Assets
    ↓
Show Statistics

Почему webpack-cli вынесен отдельно

Упрощение ядра

CLI-логика:

  • не загрязняет compiler-core;
  • не влияет на API;
  • не увеличивает complexity ядра.

Независимые обновления

CLI можно обновлять отдельно:

npm update webpack-cli

Гибкость интеграций

Webpack можно встроить:

  • в собственные платформы;
  • в облачные сервисы;
  • в CMS;
  • в IDE;
  • в enterprise build systems.

Типичная структура зависимостей

package.json

{
  "devDependencies": {
    "webpack": "^5.102.0",
    "webpack-cli": "^6.0.1"
  }
}

Как npm scripts используют webpack-cli

Пример

{
  "scripts": {
    "build": "webpack --mode production",
    "dev": "webpack --watch",
    "start": "webpack serve"
  }
}

При запуске:

npm run build

npm автоматически вызывает бинарник webpack-cli.

Как CLI находит бинарник

После установки пакета создаётся:

node_modules/.bin/webpack

Этот бинарник связан именно с webpack-cli.

Он:

  • принимает terminal-команды;
  • запускает CLI-runtime;
  • подключает ядро Webpack.

Версионная совместимость

Важно учитывать совместимость:

webpack webpack-cli
webpack 4 webpack-cli 3
webpack 5 webpack-cli 4/5/6

Несовместимые версии могут вызывать:

  • ошибки запуска;
  • проблемы с plugin API;
  • некорректную обработку конфигурации.

Типичные ошибки взаимодействия

Отсутствует CLI

webpack command not found

Конфликт версий

TypeError: compiler.getInfrastructureLogger is not a function

Ошибка конфигурации

Invalid configuration object

Ошибка загрузки config-файла

Failed to load webpack.config.js

Когда webpack-cli особенно важен

CLI особенно полезен в:

  • frontend-разработке;
  • локальной сборке;
  • dev server workflow;
  • CI pipelines;
  • monorepo;
  • multi-config проектах.

Когда можно обойтись без webpack-cli

CLI можно не использовать:

  • внутри собственных build-систем;
  • при написании платформенных инструментов;
  • в server-side automation;
  • при интеграции Webpack как библиотеки;
  • внутри enterprise tooling.

Концептуальная модель взаимодействия

Архитурно Webpack можно представить следующим образом:

webpack-cli
    ↓
webpack API
    ↓
Compiler
    ↓
Plugins + Loaders
    ↓
Assets

CLI выступает внешним управляющим слоем, а ядро Webpack — системой компиляции и трансформации модулей.

Оглавление