IgnorePlugin — встроенный механизм Webpack для исключения определённых модулей или их частей из итогового бандла на этапе сборки. Плагин работает на уровне резолва зависимостей и позволяет предотвращать попадание ненужного кода в сборку ещё до того, как он будет обработан лоадерами и включён в граф модулей. Это особенно важно для оптимизации размера бандла, сокращения времени сборки и контроля над платформенно-зависимыми зависимостями.
IgnorePlugin перехватывает процесс резолва модулей и сравнивает каждый импорт с заданными правилами. Если модуль или его часть совпадает с условиями игнорирования, Webpack полностью исключает его из графа зависимостей.
Ключевая особенность заключается в том, что модуль не просто становится “пустым” — он вообще не добавляется в сборку. Это отличает IgnorePlugin от условных проверок внутри кода или динамического импорта.
Механизм основан на хуке normalModuleFactory, через
который Webpack анализирует каждый запрос require или
import.
IgnorePlugin подключается как стандартный плагин Webpack:
const webpack = require('webpack');
module.exports = {
plugins: [
new webpack.IgnorePlugin({
resourceRegExp: /moment\/locale$/,
}),
],
};В этом примере исключаются все локализации библиотеки moment, что часто используется для уменьшения размера бандла при работе с датами.
Регулярное выражение для сопоставления имени модуля.
new webpack.IgnorePlugin({
resourceRegExp: /lodash/,
});В этом случае любой импорт, содержащий lodash, будет
проигнорирован.
Важно учитывать, что проверка происходит по строке запроса модуля, а не по фактическому пути файловой системы.
Позволяет ограничить область действия правила определённым контекстом (папкой или частью пути).
new webpack.IgnorePlugin({
resourceRegExp: /locale/,
contextRegExp: /moment$/,
});Здесь игнорируются только локали, относящиеся к moment, но не любые другие модули с похожим именем.
import 'moment/locale/ru';Если правило совпадает, модуль полностью исключается из бандла. Webpack не включает его в граф и не анализирует его зависимости.
require('moment/locale/ru');Поведение аналогично ESModules: импорт игнорируется до выполнения.
import(`moment/locale/${lang}`);IgnorePlugin не анализирует результат выражения, если оно не может быть статически определено. В таких случаях исключение не сработает, поскольку Webpack не может сопоставить строку с регулярным выражением на этапе компиляции.
Наиболее распространённый кейс — удаление ненужных языковых файлов.
new webpack.IgnorePlugin({
resourceRegExp: /\/locale$/,
contextRegExp: /date-fns|moment|dayjs/,
});Библиотеки дат часто содержат десятки локалей, увеличивающих размер бандла без необходимости.
Некоторые библиотеки содержат код для разных сред (Node.js, браузер, Electron).
new webpack.IgnorePlugin({
resourceRegExp: /fsevents/,
});fsevents используется только на macOS и часто не нужен в
кроссплатформенной сборке.
Некоторые пакеты подтягивают тяжёлые зависимости, которые используются только в отдельных сценариях.
new webpack.IgnorePlugin({
resourceRegExp: /debug/,
contextRegExp: /express/,
});IgnorePlugin работает на уровне сборщика, тогда как tree shaking — на уровне анализа экспортов.
| Механизм | Уровень | Особенности |
|---|---|---|
| IgnorePlugin | Резолв модулей | Полное исключение модуля до анализа |
| Tree shaking | AST анализ | Удаление неиспользуемых экспортов |
| DefinePlugin | Код | Замена констант |
Ключевое отличие заключается в том, что IgnorePlugin предотвращает сам факт попадания модуля в граф зависимостей.
require(`./modules/${name}`);Такие конструкции не могут быть обработаны точечно, и IgnorePlugin становится неприменимым.
Если модуль исключён, но в коде остаются обращения к его функциональности, ошибка проявится только во время выполнения.
new webpack.IgnorePlugin({
resourceRegExp: /optional-lib/,
});import optional from 'optional-lib';
optional(); // runtime error, если модуль исключён полностьюIgnorePlugin использует только регулярные выражения. Он не поддерживает сложные условия, функции или динамическую логику.
Часто используется связка, где один плагин исключает модуль, а другой управляет условным кодом.
plugins: [
new webpack.DefinePlugin({
__DEV__: JSON.stringify(false),
}),
new webpack.IgnorePlugin({
resourceRegExp: /debug/,
}),
];При код-сплиттинге IgnorePlugin помогает предотвратить попадание лишних модулей в чанки, уменьшая их размер.
optimization: {
splitChunks: {
chunks: 'all',
},
}IgnorePlugin при этом снижает объём исходного графа, который splitChunks анализирует.
Moment.js известен большим количеством локалей.
new webpack.IgnorePlugin({
resourceRegExp: /locale/,
contextRegExp: /moment/,
});Результат — уменьшение размера сборки на десятки процентов в проектах, где локализация не используется.
При сборке фронтенда иногда случайно подтягиваются серверные зависимости.
new webpack.IgnorePlugin({
resourceRegExp: /^fs$|^net$|^tls$/,
});IgnorePlugin работает одинаково в обоих режимах, поскольку он не зависит от оптимизаций минификации или tree shaking. Разница заключается только в том, что в production эффект становится более заметным из-за полного удаления лишнего кода.
Webpack строит граф модулей до этапа оптимизации. IgnorePlugin вмешивается в этот процесс, сокращая сам граф:
Это делает его одним из наиболее “ранних” механизмов оптимизации.
resourceRegExp: /lib/Такое правило может случайно исключить критически важные модули.
Удаление модуля без анализа его использования часто приводит к ошибкам выполнения, особенно в больших проектах с транзитивными зависимостями.
IgnorePlugin работает по строке запроса, а не по resolved alias. Поэтому алиасы могут обходить правила игнорирования.
В некоторых случаях вместо IgnorePlugin используют:
resolve.alias для перенаправления модулейexternals для исключения библиотек из бандлаif (false) + dead code
eliminationКаждый из этих подходов решает задачу на другом уровне, но IgnorePlugin остаётся наиболее прямым способом исключения модулей на этапе резолва.