Как настроить webpack и запустить webpack dev server

Webpack собирает модули JavaScript, стили и ресурсы в файлы для браузера. Вы создадите проект, настроите entry и output, подключите плагины и загрузчики, запустите webpack dev server и очистите папку dist. Для работы понадобятся Node.js и npm, а примеры рассчитаны на webpack 5.

Webpack: что это

Webpack – статический сборщик модулей для JavaScript-проектов. Он начинает работу с точки входа и строит граф зависимостей по операторам import и require.

Затем webpack обрабатывает найденные модули и создает один или несколько бандлов. Браузер получает эти файлы из каталога сборки и не разбирает исходную структуру проекта.

Граф зависимостей связывает файл entry с импортами, стилями и ресурсами. Поэтому одна команда может собрать связанные части проекта в готовые файлы.

Базовые понятия webpack

Пять настроек объясняют большую часть базовой конфигурации. Разберитесь с их ролями, затем перенесите значения в файл webpack.config.js.

• Entry – точка входа, с которой webpack начинает строить граф зависимостей. Для учебного проекта это ./src/index.js.
• Output – место и имя созданных файлов. Обычно сборка попадает в каталог dist.
• Loader – обработчик модуля определенного типа. Babel преобразует JavaScript, а css-loader читает зависимости CSS.
• Plugin – расширение для задач всей сборки. html-webpack-plugin создает HTML-файл и подключает к нему бандл.
• Mode – режим оптимизации. Webpack поддерживает development, production и none. Если mode не задан, webpack использует production.

Webpack читает entry, проходит по импортам, применяет подходящие rules и записывает результат через output. Свойства entry и output не заменяют друг друга.

Установка webpack

Для сборки нужны Node.js и npm. Установите Node.js с официального сайта, выбрав выпуск LTS. npm устанавливается вместе с Node.js и запускает команды из файла package.json.

Откройте терминал и проверьте установку командами node --version и npm --version. Каждая команда должна вывести номер установленной версии.

Создайте каталог проекта и откройте его в терминале:

mkdir learn-webpack
cd learn-webpack
npm init -y
npm install --save-dev webpack@5 webpack-cli

Команда добавит webpack и webpack-cli в devDependencies проекта. Версии установленных пакетов покажет команда npx webpack --version.

Создайте каталог src и файл src/index.js:

const message = document.createElement('p');
message.textContent = 'Hello webpack';
document.body.appendChild(message);

Откройте package.json и замените объект scripts:

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

Остальные поля package.json оставьте без изменений. Если после scripts идет другое поле, сохраните запятую между ними.

Запустите npm run dev. Webpack соберет entry и запишет бандл в каталог dist. Если команда завершилась без ошибки, в выводе появится созданный asset.

Подключение html-webpack-plugin

Ручной HTML-файл быстро устаревает, если меняется имя бандла. html-webpack-plugin создает HTML во время сборки и сам добавляет в него подключенные assets.

npm install --save-dev html-webpack-plugin

Создайте webpack.config.js в корне проекта:

const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  plugins: [
    new HtmlWebpackPlugin({
      title: 'Webpack Output'
    })
  ]
};

Запустите npm run build. Webpack положит index.html в dist и подставит в него имя созданного JavaScript-файла.

Настройка webpack.config.js

В конфиге задайте entry и output явно. Свойство entry указывает исходный модуль, а output описывает результат сборки.

const path = require('path');
const HtmlWebpackPlugin = require('html-webpack-plugin');

module.exports = {
  mode: 'development',
  entry: './src/index.js',
  output: {
    filename: '[name].bundle.js',
    path: path.resolve(__dirname, 'dist'),
    clean: true
  },
  plugins: [
    new HtmlWebpackPlugin({
      title: 'Webpack Output'
    })
  ]
};

Скопируйте конфигурацию целиком в webpack.config.js. Параметр filename создаст файл main.bundle.js, а path укажет абсолютный путь к dist. Свойства entry и output отвечают за разные части сборки.

После npm run build в dist появятся index.html и main.bundle.js. Откройте папку dist и дважды щелкните файл index.html. Браузер откроет страницу, а подключенный скрипт добавит текст «Hello webpack».

Работа со скриптами и Babel

Webpack собирает модули, но сам по себе не превращает современный синтаксис JavaScript в ES5. Babel выполняет такую трансформацию через babel-loader.

npm install --save-dev babel-loader @babel/core @babel/preset-env

Добавьте свойство module в корневой объект module.exports файла webpack.config.js. Отделите его запятой от соседних свойств:

module: {
  rules: [
    {
      test: /\.js$/,
      exclude: /node_modules/,
      use: {
        loader: 'babel-loader',
        options: {
          presets: ['@babel/preset-env']
        }
      }
    }
  ]
}

• test выбирает файлы по регулярному выражению.
• exclude исключает зависимости из node_modules.
• use назначает загрузчик и его настройки.

Для сборки под старые браузеры задайте target ['web', 'es5'] или используйте browserslist. Babel преобразует исходные модули, а target помогает webpack выбрать совместимый служебный код.

Добавьте target рядом с entry в корневой объект конфигурации:

target: ['web', 'es5'],

Вызовите npm run build. Babel обработает исходный модуль по правилам @babel/preset-env. Настройка target не добавляет поддержку браузерных API: для отсутствующих возможностей нужны полифилы.

Чтобы рассмотреть преобразованный код без source maps, запустите npm run dev -- --no-devtool. Тот же результат дает devtool: false в корневом объекте конфигурации. Содержимое бандла можно открыть в текстовом редакторе.

Как подключить CSS через css-loader и style-loader

Для подключения CSS установите css-loader и style-loader. Первый читает CSS и его зависимости, второй добавляет стили в тег <style> страницы.

npm install --save-dev css-loader style-loader

Добавьте правило для CSS в массив module.rules рядом с правилом Babel. Разделите объекты правил запятой:

{
  test: /\.css$/,
  use: ['style-loader', 'css-loader']
}

Создайте файл src/style.css:

p {
  color: red;
}

Добавьте импорт CSS в начало src/index.js. Полное содержимое файла будет таким:

import './style.css';

const message = document.createElement('p');
message.textContent = 'Hello webpack';
document.body.appendChild(message);

Запустите npm run dev и снова откройте dist/index.html. Webpack обработает CSS, а текст на странице получит красный цвет.

Как подключить изображения через asset modules

В старых конфигурациях webpack file loader обрабатывал изображения и возвращал их URL. В webpack 5 эту задачу выполняют встроенные asset modules.

Добавьте правило в тот же массив module.rules:

{
  test: /\.(png|jpe?g|gif)$/,
  type: 'asset/resource'
}

Скопируйте PNG-изображение в каталог src и назовите его image.png. Создайте рядом файл src/image-component.js:

import image from './image.png';

const img = document.createElement('img');
img.src = image;
img.alt = 'Иллюстрация проекта';
document.body.appendChild(img);

Подключите компонент в src/index.js:

import './style.css';
import './image-component';

const message = document.createElement('p');
message.textContent = 'Hello webpack';
document.body.appendChild(message);

После npm run build webpack скопирует изображение в dist и вернет его путь импортирующему модулю. Имя файла может содержать хеш, поэтому компонент использует импорт.

Откройте dist/index.html в браузере. Над красным текстом появится выбранное изображение.

Изменения webpack 4 и webpack 5

Старые примеры часто ломаются из-за названий опций и отдельных загрузчиков. При настройке webpack 5 и его dev-сервера учитывайте следующие различия:

Не переносите старый конфиг целиком. Проверьте назначение каждой опции и используйте настройки из примера.

Как запустить webpack dev server

Webpack dev server собирает проект в памяти и обновляет страницу после изменения исходников. Установите пакет:

npm install --save-dev webpack-dev-server

Измените скрипт dev в package.json:

"dev": "webpack serve --mode development"

Добавьте свойство devServer в корневой объект webpack.config.js:

devServer: {
  static: './dist',
  open: true,
  hot: true
}

Опция static указывает каталог для статических файлов. Параметр open открывает страницу после запуска, а hot включает горячее обновление модулей.

Запустите npm run dev. В терминале появится адрес локального сервера, а браузер откроет страницу. Сервер отдает собранные файлы из памяти, поэтому содержимое dist может не меняться.

В файле src/style.css замените red на blue и сохраните изменения. Текст станет синим без полной перезагрузки благодаря горячему обновлению модулей (HMR). Изменения JavaScript могут вызвать перезагрузку, если модуль не настроен на прием обновлений.

Остановите сервер сочетанием Ctrl+C в терминале. После изменения конфигурации запустите npm run dev заново.

Кеширование сборки

Webpack 5 умеет хранить кеш на диске. Такая настройка сокращает повторную обработку неизмененных модулей между запусками.

Добавьте свойство cache в корневой объект конфигурации:

cache: {
  type: 'filesystem'
}

Для кеширования браузером добавьте хеш содержимого в имя файла. Замените существующий объект output:

output: {
  filename: '[name].[contenthash].js',
  path: path.resolve(__dirname, 'dist'),
  clean: true
}

Webpack создает новое имя после изменения содержимого бандла. html-webpack-plugin автоматически подключит файл с новым именем.

Запустите npm run build и посмотрите имена файлов в dist. Теперь имя JavaScript-файла содержит хеш. Дисковый кеш ускоряет работу сборщика, а хеш помогает браузеру различать версии бандла.

Как очистить dist перед сборкой

После изменения имен файлов в dist могут остаться старые бандлы. Параметр output.clean: true очищает каталог вывода перед записью результата сборки.

output: {
  filename: '[name].[contenthash].js',
  path: path.resolve(__dirname, 'dist'),
  clean: true
}

Храните исходники и нужные вручную добавленные файлы вне dist. Очистка затрагивает каталог вывода, поэтому он должен содержать только результат сборки.

Создайте пустой файл dist/old.txt и запустите npm run build. Файл old.txt исчезнет, а в каталоге останутся файлы новой сборки.

Как проверить сборку и сервер разработки webpack

Минимальный проект использует Node.js, npm, entry, output и mode. html-webpack-plugin создает HTML, loaders обрабатывают JavaScript и CSS, asset modules подключают изображения, а webpack dev server ускоряет локальную разработку.

Проверьте проект командами npm run dev и npm run build. В первом случае сервер обновляет страницу после сохранения, во втором в dist появляется production-результат.

Дополнительные сведения ищите в разделах Getting Started, Concepts, Asset Modules и DevServer официальной документации webpack.

Сохраните копию рабочего конфига перед добавлением нового loader. Если сборка перестанет запускаться, восстановите файл из копии и повторите команду.