Установка Webpack — первый этап подготовки среды сборки frontend-приложения. От способа установки зависит:

• доступность CLI-команд;
• изоляция зависимостей между проектами;
• совместимость версий;
• воспроизводимость окружения;
• удобство командной работы;
• интеграция с CI/CD.

Webpack может устанавливаться:

• локально — внутри конкретного проекта;
• глобально — в систему пользователя.

На практике эти способы используются для разных задач и имеют принципиальные отличия.

---

Что представляет собой Webpack после установки

После установки в проекте появляются:

• пакет webpack;
• пакет webpack-cli;
• исполняемые бинарные файлы;
• зависимости для сборки;
• API для конфигурации;
• команды запуска через npx или npm scripts.

Webpack не является самостоятельной программой вне экосистемы Node.js. Он работает как npm-пакет и управляется через менеджер пакетов:

• npm;
• yarn;
• pnpm.

---

Предварительные требования

Для установки необходим установленный Node.js.

Проверка версии Node.js:

node -v

Проверка npm:

npm -v

Webpack 5 требует современную версию Node.js. Старые версии Node могут вызывать:

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

---

Инициализация проекта

Перед локальной установкой создаётся каталог проекта.

Пример:

mkdir webpack-project
cd webpack-project

После этого выполняется инициализация npm:

npm init -y

Файл package.json становится центральной точкой управления зависимостями проекта.

Пример минимального package.json:

{
  "name": "webpack-project",
  "version": "1.0.0"
}

---

Локальная установка Webpack

Суть локальной установки

Локальная установка помещает Webpack внутрь проекта.

Пакеты сохраняются в:

node_modules/

Информация о зависимостях записывается в:

package.json

Именно локальная установка считается стандартом современной frontend-разработки.

---

Установка webpack и webpack-cli

Минимальный набор включает два пакета:

npm install webpack webpack-cli --save-dev

Или сокращённо:

npm i webpack webpack-cli -D

---

Роль webpack-cli

Пакет webpack содержит механизм сборки.

Пакет webpack-cli предоставляет:

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

Без webpack-cli команды вроде:

npx webpack

не будут работать корректно.

---

Почему используется –save-dev

Webpack относится к инструментам разработки, а не runtime-зависимостям.

Поэтому он записывается в раздел:

"devDependencies"

Пример:

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

Такие зависимости:

• нужны только при разработке;
• не требуются браузеру;
• не входят в production runtime;
• устанавливаются отдельно на CI/CD.

---

Структура проекта после установки

После установки структура проекта становится примерно такой:

project/
├── node_modules/
├── package.json
├── package-lock.json

Назначение package-lock.json

Файл lock-зависимостей:

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

---

Где располагаются бинарные файлы Webpack

При локальной установке бинарные файлы помещаются в:

node_modules/.bin/

Например:

node_modules/.bin/webpack

Именно поэтому npm scripts могут запускать Webpack без глобальной установки.

---

Запуск локального Webpack через npx

Современный стандарт запуска:

npx webpack

Команда npx:

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

Это критически важно для согласованности версий.

---

Использование npm scripts

Чаще всего Webpack запускается через scripts.

Пример:

{
  "scripts": {
    "build": "webpack",
    "dev": "webpack --mode development"
  }
}

Запуск:

npm run build

или:

npm run dev

---

Преимущества локальной установки

Изоляция зависимостей

Каждый проект использует собственную версию Webpack.

Это позволяет:

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

---

Предсказуемость окружения

Команда разработчиков получает одинаковую конфигурацию.

После выполнения:

npm install

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

---

Совместимость CI/CD

Системы непрерывной интеграции работают именно с локальными зависимостями.

Например:

• GitHub Actions;
• GitLab CI;
• Jenkins;
• TeamCity.

---

Отсутствие зависимости от системы пользователя

Проект не требует:

• предварительной настройки ОС;
• ручной установки Webpack;
• глобальных пакетов.

---

Безопасность обновлений

Обновление Webpack затрагивает только текущий проект.

Другие приложения остаются неизменными.

---

Недостатки локальной установки

Увеличение размера node_modules

Webpack имеет большое дерево зависимостей.

Папка node_modules может занимать сотни мегабайт.

---

Повторная установка между проектами

Каждый проект хранит собственную копию Webpack.

Это увеличивает расход дискового пространства.

---

Более длинные команды без scripts

Прямой запуск требует:

npx webpack

вместо простой команды:

webpack

---

Глобальная установка Webpack

Суть глобальной установки

Глобальная установка делает пакет доступным во всей системе.

Команда:

npm install -g webpack webpack-cli

После этого Webpack можно запускать из любого каталога:

webpack

---

Где располагаются глобальные пакеты

Расположение зависит от ОС и менеджера Node.js.

Типичные пути:

Windows

C:\Users\Username\AppData\Roaming\npm

Linux/macOS

/usr/local/lib/node_modules

или:

~/.npm-global

---

Проверка глобальной установки

Проверка версии:

webpack -v

или:

webpack --version

---

Преимущества глобальной установки

Быстрый доступ к CLI

Webpack доступен в терминале без npx.

---

Удобство для экспериментов

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

• тестирования;
• учебных примеров;
• временных проектов;
• быстрой генерации сборок.

---

Экономия места

Одна глобальная установка может использоваться многими проектами.

---

Недостатки глобальной установки

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

Разные проекты могут требовать разные версии Webpack.

Глобальная установка создаёт проблему совместимости.

Например:

• старый проект требует Webpack 4;
• новый проект использует Webpack 5.

Одновременно использовать обе версии через глобальный пакет неудобно.

---

Непредсказуемость окружения

Проект начинает зависеть от системы разработчика.

На другой машине Webpack может:

• отсутствовать;
• иметь другую версию;
• работать иначе.

---

Проблемы CI/CD

Серверы сборки обычно не используют глобальные пакеты.

Это нарушает воспроизводимость.

---

Сложности командной разработки

Невозможно гарантировать, что у всей команды одинаковая версия Webpack.

---

Проблемы обновления

Обновление глобального Webpack влияет сразу на все проекты.

Это может ломать старые конфигурации.

---

Почему локальная установка считается стандартом

Современная экосистема JavaScript ориентирована на:

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

Поэтому практически все production-проекты используют локальную установку.

Глобальная установка чаще применяется:

• для учебных целей;
• в песочницах;
• при быстром прототипировании;
• для внутренних CLI-инструментов.

---

Сравнение локальной и глобальной установки

Характеристика	Локальная	Глобальная
Изоляция версий	Да	Нет
Подходит для production	Да	Ограниченно
Работает в CI/CD	Да	Нежелательно
Доступность команды webpack	Через npx/npm scripts	Глобально
Совместимость между проектами	Высокая	Низкая
Зависимость от окружения	Минимальная	Высокая
Простота запуска	Средняя	Высокая
Контроль версий	Полный	Ограниченный

---

Установка определённой версии Webpack

Иногда требуется фиксированная версия.

Пример:

npm install webpack@5.98.0 webpack-cli@5.1.4 --save-dev

Это необходимо:

• при поддержке legacy-проектов;
• для совместимости loader-пакетов;
• при воспроизводимых сборках;
• при миграции между major-версиями.

---

Проверка установленной версии

Локальная версия:

npx webpack --version

Глобальная версия:

webpack --version

---

Удаление Webpack

Удаление локального пакета

npm uninstall webpack webpack-cli

---

Удаление глобального пакета

npm uninstall -g webpack webpack-cli

---

Использование yarn

Локальная установка:

yarn add webpack webpack-cli --dev

Глобальная установка:

yarn global add webpack webpack-cli

---

Использование pnpm

Локальная установка:

pnpm add webpack webpack-cli -D

Глобальная установка:

pnpm add -g webpack webpack-cli

---

Проверка доступности webpack-cli

Иногда Webpack установлен, но CLI отсутствует.

Типичная ошибка:

CLI for webpack must be installed.

Решение:

npm install webpack-cli --save-dev

---

Типичные проблемы при установке

Permission denied

Часто возникает в Linux/macOS при глобальной установке.

Неправильный подход:

sudo npm install -g webpack

Лучше использовать:

• nvm;
• fnm;
• Volta.

---

Команда webpack не найдена

Причины:

• пакет не установлен;
• npm global path отсутствует в PATH;
• повреждённый node_modules;
• отсутствует webpack-cli.

---

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

Некоторые loader-пакеты требуют конкретную версию Node.js.

Проверка:

node -v

---

Повреждённые зависимости

Иногда помогает полная переустановка:

rm -rf node_modules
rm package-lock.json
npm install

---

Практическая схема установки для production-проектов

Наиболее распространённая последовательность:

1. Инициализация проекта

npm init -y

---

2. Установка Webpack локально

npm install webpack webpack-cli --save-dev

---

3. Добавление scripts

{
  "scripts": {
    "build": "webpack",
    "watch": "webpack --watch"
  }
}

---

4. Запуск сборки

npm run build

---

Роль npx в современной экосистеме

До появления npx глобальная установка использовалась значительно чаще.

Сейчас npx решает большинство проблем:

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

Поэтому сочетание:

npm install webpack webpack-cli -D

и:

npx webpack

стало фактическим стандартом разработки на Webpack.