Требования к окружению: Node.js и npm/yarn/pnpm

Webpack является инструментом, работающим внутри среды выполнения Node.js. Несмотря на то что конечной целью Webpack обычно становится сборка клиентского JavaScript-кода для браузера, сам процесс сборки выполняется именно через Node.js. По этой причине корректно подготовленное окружение — фундамент стабильной работы проекта.

Webpack использует возможности Node.js для:

  • чтения и анализа файловой системы;
  • построения графа зависимостей;
  • выполнения JavaScript вне браузера;
  • подключения загрузчиков (loaders);
  • работы плагинов;
  • запуска dev server;
  • обработки конфигурационных файлов;
  • выполнения Babel, TypeScript, PostCSS и других инструментов.

Без установленного Node.js Webpack не может быть запущен.

Что такое Node.js

Node.js — это серверная среда выполнения JavaScript, построенная на движке V8. Она позволяет запускать JavaScript-код вне браузера.

Webpack использует Node.js как платформу исполнения. При запуске команды:

webpack

или:

npx webpack

фактически запускается Node.js-процесс.

Что такое npm

npm — стандартный менеджер пакетов, поставляемый вместе с Node.js.

После установки Node.js автоматически становятся доступны:

node
npm
npx

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

  • установку Webpack;
  • установку зависимостей проекта;
  • управление версиями пакетов;
  • запуск scripts из package.json;
  • загрузку библиотек из npm registry.

Пример установки Webpack через npm:

npm install webpack webpack-cli --save-dev

Что такое Yarn

Yarn — альтернативный менеджер пакетов, разработанный компанией Meta.

Yarn появился как решение некоторых проблем старых версий npm:

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

Пример установки Webpack через Yarn:

yarn add webpack webpack-cli --dev

Что такое pnpm

pnpm — современный пакетный менеджер с оптимизированным хранением зависимостей.

Главные особенности pnpm:

  • высокая скорость установки;
  • экономия места на диске;
  • строгая структура node_modules;
  • эффективное кэширование;
  • хорошая совместимость с monorepo.

Установка Webpack через pnpm:

pnpm add webpack webpack-cli -D

Почему Webpack требует пакетный менеджер

Webpack редко используется изолированно. Типичный современный проект включает десятки или сотни зависимостей:

  • Babel;
  • TypeScript;
  • React;
  • Vue;
  • Sass;
  • PostCSS;
  • ESLint;
  • loaders;
  • plugins.

Пакетный менеджер автоматически:

  • скачивает зависимости;
  • разрешает версии;
  • строит дерево зависимостей;
  • сохраняет информацию в lock-файлах;
  • обеспечивает воспроизводимость сборки.

Минимальные требования к Node.js

Разные версии Webpack поддерживают разные версии Node.js.

Для современных версий Webpack обычно требуется актуальная LTS-версия Node.js.

На практике рекомендуется:

Webpack Рекомендуемый Node.js
Webpack 4 Node.js 10–14
Webpack 5 Node.js 16+
Современные экосистемы Node.js 18+

Использование устаревших версий Node.js приводит к:

  • ошибкам совместимости;
  • проблемам ESM;
  • невозможности установки пакетов;
  • сбоям dev server;
  • ошибкам OpenSSL;
  • несовместимости плагинов.

LTS-версии Node.js

Node.js выпускается в двух основных ветках:

Тип Назначение
Current Новые возможности
LTS Долгосрочная поддержка

Для Webpack-проектов почти всегда используется именно LTS.

Причины:

  • стабильность;
  • поддержка экосистемы;
  • совместимость библиотек;
  • меньше breaking changes;
  • предсказуемое поведение CI/CD.

Проверка установленного окружения

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

node -v

Проверка npm:

npm -v

Проверка Yarn:

yarn -v

Проверка pnpm:

pnpm -v

Установка Node.js

Основной способ установки — официальный сайт Node.js.

Node.js

После установки обычно доступны:

node
npm
npx

Что такое npx

npx — инструмент для запуска локально установленных npm-пакетов.

Пример:

npx webpack

Без npx пришлось бы:

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

npx автоматически ищет пакет внутри:

node_modules/.bin

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

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

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

npm install webpack webpack-cli --save-dev

или:

pnpm add webpack webpack-cli -D

Преимущества:

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

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

Пример:

npm install -g webpack webpack-cli

Недостатки:

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

В современных проектах глобальная установка почти не используется.

package.json как основа окружения

Файл:

package.json

содержит описание проекта и зависимостей.

Пример:

{
  "name": "webpack-project",
  "version": "1.0.0",
  "scripts": {
    "build": "webpack",
    "start": "webpack serve"
  },
  "devDependencies": {
    "webpack": "^5.102.0",
    "webpack-cli": "^6.0.1"
  }
}

Webpack обычно запускается через scripts:

npm run build

lock-файлы и воспроизводимость окружения

Каждый пакетный менеджер использует собственный lock-файл:

Менеджер Lock-файл
npm package-lock.json
Yarn yarn.lock
pnpm pnpm-lock.yaml

Lock-файлы фиксируют:

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

Это гарантирует одинаковую установку на:

  • локальной машине;
  • сервере;
  • CI/CD;
  • компьютерах команды.

node_modules и структура зависимостей

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

node_modules

Внутри находятся:

  • Webpack;
  • loaders;
  • plugins;
  • Babel;
  • React;
  • все вложенные зависимости.

Webpack активно взаимодействует с этой структурой.

Отличия npm, Yarn и pnpm

npm

Преимущества:

  • устанавливается вместе с Node.js;
  • стандарт де-факто;
  • высокая совместимость;
  • зрелая экосистема.

Недостатки старых версий:

  • медленная установка;
  • большой размер node_modules.

Yarn

Преимущества:

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

Недостатки:

  • часть преимуществ утратилась после улучшений npm;
  • существуют различия между Yarn Classic и Yarn Berry.

pnpm

Преимущества:

  • очень высокая скорость;
  • минимальный расход диска;
  • строгая изоляция зависимостей;
  • эффективная работа с monorepo.

Недостатки:

  • некоторые старые пакеты несовместимы;
  • отдельные инструменты ожидают плоскую структуру node_modules.

Почему pnpm становится популярным в Webpack-проектах

Современные фронтенд-проекты могут содержать:

  • тысячи пакетов;
  • десятки loaders;
  • множество транспайлеров;
  • сложные monorepo.

pnpm значительно снижает:

  • объём node_modules;
  • время CI;
  • нагрузку на файловую систему;
  • дублирование зависимостей.

Особенно это важно для крупных проектов.

Переменные окружения

Webpack активно использует переменные окружения.

Примеры:

NODE_ENV=production

или:

NODE_ENV=development

Node.js передаёт эти значения в процесс сборки.

Webpack использует их для:

  • production mode;
  • tree shaking;
  • минификации;
  • dead code elimination;
  • оптимизации bundle.

NODE_ENV и режимы Webpack

Webpack поддерживает режимы:

mode: 'development'

и:

mode: 'production'

Часто они связаны с:

NODE_ENV

Пример:

{
  "scripts": {
    "build": "NODE_ENV=production webpack"
  }
}

Проблемы совместимости Windows и Unix

Unix-системы:

NODE_ENV=production webpack

Windows CMD:

set NODE_ENV=production && webpack

Для кроссплатформенности используют:

cross-env

Пример:

npm install cross-env --save-dev

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

В проектах часто используется файл:

.nvmrc

Он фиксирует версию Node.js:

18

или:

20.11.1

Это важно для:

  • командной разработки;
  • CI;
  • серверов;
  • стабильности сборок.

Node Version Manager

nvm позволяет переключаться между версиями Node.js.

Примеры:

nvm install 20
nvm use 20

Это особенно важно при поддержке нескольких Webpack-проектов.

Corepack

Современные версии Node.js включают:

Corepack

Corepack управляет версиями:

  • Yarn;
  • pnpm.

Пример активации:

corepack enable

После этого можно использовать:

pnpm
yarn

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

Особенности ESM и CommonJS

Современный Node.js поддерживает:

  • CommonJS;
  • ECMAScript Modules.

Webpack также взаимодействует с обеими системами модулей.

Пример CommonJS:

const path = require('path');

Пример ESM:

import path fr om 'path';

Некоторые версии Node.js имеют ограничения совместимости ESM, поэтому актуальная версия среды крайне важна.

Влияние версии Node.js на производительность сборки

Новые версии Node.js улучшают:

  • скорость V8;
  • работу garbage collector;
  • производительность файловой системы;
  • асинхронные операции;
  • кеширование.

В больших Webpack-проектах это напрямую влияет на:

  • cold build;
  • incremental build;
  • HMR;
  • startup dev server.

CI/CD и требования к окружению

В CI-системах версия Node.js должна быть строго фиксированной.

Пример для GitHub Actions:

- uses: actions/setup-node@v4
  with:
    node-version: 20

Несовпадение версий Node.js между:

  • локальной машиной;
  • CI;
  • production server

часто приводит к трудноуловимым ошибкам.

Типичные проблемы окружения

Устаревший Node.js

Ошибка:

Unexpected token

или:

Cannot use import statement outside a module

Причина:

  • старая версия Node.js;
  • отсутствие поддержки современного синтаксиса.

Конфликт lock-файлов

Наличие одновременно:

package-lock.json
yarn.lock
pnpm-lock.yaml

создаёт конфликт менеджеров пакетов.

В проекте обычно используется только один пакетный менеджер.

Повреждённый node_modules

Иногда помогает:

rm -rf node_modules

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

На Windows:

rmdir /s node_modules

Несовместимость зависимостей

Webpack-экосистема быстро развивается.

Конфликты часто возникают между:

  • webpack;
  • webpack-cli;
  • loaders;
  • plugins;
  • Babel;
  • TypeScript.

Поэтому важно контролировать версии пакетов.

DevDependencies и Dependencies

Webpack обычно относится к:

"devDependencies"

Причина:

  • Webpack нужен только на этапе сборки;
  • в production bundle Webpack не используется.

Пример:

{
  "devDependencies": {
    "webpack": "^5.0.0"
  }
}

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

Основной пакет:

webpack

не содержит полноценного интерфейса командной строки.

CLI находится в отдельном пакете:

webpack-cli

Поэтому обычно устанавливаются оба пакета:

npm install webpack webpack-cli --save-dev

Webpack Dev Server и Node.js

webpack-dev-server запускается как Node.js-приложение.

Он использует:

  • HTTP-сервер;
  • WebSocket;
  • файловые watchers;
  • HMR;
  • middleware.

Производительность dev server напрямую зависит от Node.js и файловой системы ОС.

Монорепозитории и пакетные менеджеры

В крупных проектах используются monorepo:

  • Nx;
  • Turborepo;
  • Rush;
  • Lerna.

В таких структурах pnpm особенно эффективен благодаря:

  • shared store;
  • symlink architecture;
  • минимизации дубликатов.

Webpack при этом может использоваться внутри отдельных пакетов monorepo.

Влияние файловой системы на Webpack

Node.js взаимодействует с файловой системой напрямую.

Скорость сборки зависит от:

  • SSD/HDD;
  • количества файлов;
  • производительности watchers;
  • ограничений ОС.

Особенно чувствительны:

  • large monorepo;
  • thousands modules;
  • massive node_modules.

Watch mode и системные ограничения

Webpack watch mode использует системные наблюдатели файлов.

В Linux возможны ограничения:

ENOSPC: System lim it for number of file watchers reached

Это связано не с Webpack напрямую, а с лимитами ОС и Node.js watchers.

Требования к памяти

Большие проекты могут потреблять значительный объём памяти.

Node.js имеет ограничение heap size.

Иногда требуется:

node --max-old-space-size=4096

или:

NODE_OPTIONS=--max-old-space-size=4096

Это особенно актуально для:

  • production build;
  • source maps;
  • больших SPA;
  • сложных optimization plugins.
Оглавление