Интерфейс узла

webpack предоставляет API Node.js, который можно использовать непосредственно в среде выполнения Node.js.

API Node.js полезен в сценариях, в которых требуется настроить процесс сборки или разработки, поскольку все отчеты и обработка ошибок должны выполняться вручную, а webpack выполняет только компиляцию. По этой причине параметры конфигурации stats не будут иметь никакого эффекта в вызове webpack().

Установка

Чтобы начать использовать API Node.js webpack, сначала установите webpack, если вы этого еще не сделали:

npm install --save-dev webpack

Затем импортируйте модуль webpack в ваш скрипт Node.js:

const webpack = require('webpack');

Или, если вы предпочитаете ES2015:

import webpack from 'webpack';

webpack()

Импортированная webpack функция получает объект конфигурации webpack Configuration Object и запускает компилятор webpack, если предоставлена функция обратного вызова:

const webpack = require('webpack');

webpack({
  // Configuration Object
}, (err, stats) => { // Stats Object
  if (err || stats.hasErrors()) {
    // Handle errors here
  }
  // Done processing
});

Объект err не будет содержать ошибки компиляции. Их необходимо обрабатывать отдельно, используя stats.hasErrors(), что будет подробно рассмотрено в разделе «Обработка ошибок» этого руководства. Объект err будет содержать только проблемы, связанные с webpack, такие как неправильная настройка и т. д.

Вы можете предоставить функции webpack массив конфигураций. Дополнительную информацию см. в разделе «Многокомпилятор» ниже.

Экземпляр компилятора

Если вы не передаете функцию запуска webpack обратный вызов, она вернет экземпляр webpack Compiler. Этот экземпляр можно использовать для ручного запуска исполнителя webpack или для построения и отслеживания изменений, аналогично CLI. Экземпляр Compiler предоставляет следующие методы:

• .run(callback)
• .watch(watchOptions, handler)

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

Свойство hooks экземпляра Compiler используется для регистрации плагина для любого события-обработчика в жизненном цикле Compiler. Утилиты WebpackOptionsDefaulter и WebpackOptionsApply используются webpack для настройки своего экземпляра Compiler со всеми встроенными плагинами.

Метод run используется для запуска всех работ по компиляции. После завершения выполняется указанная функция callback. Конечная регистрация статистики и ошибок должна выполняться в этой функции callback.

API поддерживает только одну одновременную компиляцию. При использовании run, дождитесь ее завершения, прежде чем повторно вызывать run или watch. При использовании watch, вызовите close и дождитесь его завершения, прежде чем повторно вызывать run или watch. Одновременные компиляции приведут к повреждению выходных файлов.

Запуск

Вызов метода run на экземпляре Compiler аналогичен методу быстрого запуска, упомянутому выше:

const webpack = require('webpack');

const compiler = webpack({
  // Configuration Object
});

compiler.run((err, stats) => { // Stats Object
  // ...
});

Отслеживание

Вызов метода watch запускает исполнителя webpack, но затем следит за изменениями (аналогично CLI: webpack --watch), как только webpack обнаружит изменение, он повторно выполняется. Возвращает экземпляр Watching.

watch(watchOptions, callback);

const webpack = require('webpack');

const compiler = webpack({
  // Configuration Object
});

const watching = compiler.watch({
  // Example watchOptions
  aggregateTimeout: 300,
  poll: undefined
}, (err, stats) => { // Stats Object
  // Print watch/build result here...
  console.log(stats);
});

Параметры Watching подробно описаны здесь.

Неточности файловой системы могут вызывать несколько сборок для одного изменения. Таким образом, в примере выше оператор console.log может срабатывать несколько раз для одного изменения. Пользователи должны ожидать этого поведения и могут проверить stats.hash для определения того, действительно ли изменился хэш файла.

Закрытие отслеживания

Метод watch возвращает экземпляр Watching , который предоставляет метод .close(callback). Вызов этого метода завершит отслеживание:

watching.close(() => {
  console.log('Watching Ended.');
});

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

Сделать отслеживание недействительным

Используя watching.invalidate, вы можете вручную сделать текущий раунд компиляции недействительным, не останавливая процесс отслеживания:

watching.invalidate();

Объект статистики

Объект stats, передаваемый в качестве второго аргумента обратного вызова webpack(), является хорошим источником информации о процессе компиляции кода. Он включает:

• Ошибки и предупреждения (при наличии)
• Временные метки
• Информация о модулях и блоках

Webpack CLI использует эту информацию для отображения отформатированного вывода в вашей консоли.

При использовании MultiCompiler, возвращается экземпляр MultiStats, который удовлетворяет тому же интерфейсу, что и stats, то есть методам, описанным ниже.

Этот объект stats предоставляет следующие методы:

stats.hasErrors()

Может использоваться для проверки наличия ошибок во время компиляции. Возвращает true или false.

stats.hasWarnings()

Может использоваться для проверки наличия предупреждений во время компиляции. Возвращает true или false.

stats.toJson(options)

Возвращает информацию о компиляции в виде объекта JSON. options может быть строкой (пресет) или объектом для более точного управления:

stats.toJson('minimal'); // more options: 'verbose', etc.

stats.toJson({
  assets: false,
  hash: true
});

Все доступные параметры и пресеты описаны в документации по статистике здесь.

Вот пример вывода этой функции здесь.

stats.toString(options)

Возвращает отформатированную строку информации о компиляции (аналогично выводу CLI).

Параметры такие же, как и в stats.toJson(options) с одним дополнением:

stats.toString({
  // Add console colors
  colors: true
});

Вот пример использования stats.toString():

const webpack = require('webpack');

webpack({
  // Configuration Object
}, (err, stats) => {
  if (err) {
    console.error(err);
    return;
  }

  console.log(stats.toString({
    chunks: false,  // Makes the build much quieter
    colors: true    // Shows colors in the console
  }));
});

Многокомпилятор

Модуль MultiCompiler позволяет webpack запускать несколько конфигураций в отдельных компиляторах. Если параметр options в API NodeJS webpack является массивом параметров, webpack применяет отдельные компиляторы и вызывает callback после выполнения всех компиляторов.

var webpack = require('webpack');

webpack([
  { entry: './index1.js', output: { filename: 'bundle1.js' } },
  { entry: './index2.js', output: { filename: 'bundle2.js' } }
], (err, stats) => { // Stats Object
  process.stdout.write(stats.toString() + '\n');
})

Несколько конфигураций не будут запускаться параллельно. Каждая конфигурация обрабатывается только после завершения обработки предыдущей. Для обработки параллельно можно использовать стороннее решение, например, parallel-webpack.

Обработка ошибок

Для эффективной обработки ошибок необходимо учитывать три типа ошибок:

• Критические ошибки webpack (неправильная конфигурация и т. д.)
• Ошибки компиляции (отсутствующие модули, синтаксические ошибки и т. д.)
• Предупреждения о компиляции

Вот пример, который учитывает все эти моменты:

const webpack = require('webpack');

webpack({
  // Configuration Object
}, (err, stats) => {
  if (err) {
    console.error(err.stack || err);
    if (err.details) {
      console.error(err.details);
    }
    return;
  }

  const info = stats.toJson();

  if (stats.hasErrors()) {
    console.error(info.errors);
  }

  if (stats.hasWarnings()) {
    console.warn(info.warnings);
  }

  // Log result...
});

Настраиваемые файловые системы

По умолчанию webpack считывает и записывает файлы на диск, используя обычную файловую систему. Однако можно изменить поведение ввода или вывода, используя другой тип файловой системы (память, webDAV и т. д.). Для этого можно изменить inputFileSystem или outputFileSystem. Например, можно заменить стандартную outputFileSystem на memory-fs, чтобы записывать файлы в память, а не на диск:

const MemoryFS = require('memory-fs');
const webpack = require('webpack');

const fs = new MemoryFS();
const compiler = webpack({ / options / });

compiler.outputFileSystem = fs;
compiler.run((err, stats) => {
  // Read the output later:
  const content = fs.readFileSync('...');
});

Обратите внимание, что именно это использует webpack-dev-middleware, используемый webpack-dev-server и многими другими пакетами, чтобы загадочным образом скрыть ваши файлы, но продолжать их предоставлять браузеру!

Предоставляемая вами файловая система вывода должна быть совместима с собственным интерфейсом Node fs, который требует методов-помощников mkdirp и join.