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

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

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

Установка

Чтобы начать использовать API webpack Node.js, сначала установите 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({}, (err, stats) => {
  if (err || stats.hasErrors()) {
    // ...
  }
  // Done processing
});

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

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

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

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

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

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

Запуск

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

const webpack = require('webpack');

const compiler = webpack({
  // ...
});

compiler.run((err, stats) => {
  // ...

  compiler.close((closeErr) => {
    // ...
  });
});

Наблюдение

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

watch(watchOptions, callback);

const webpack = require('webpack');

const compiler = webpack({
  // ...
});

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

Опции Watching подробно описаны здесь.

Закрытие Watching

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

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

Отмена Watching

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

watching.invalidate();

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

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

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

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

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

stats.hasErrors()

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

stats.hasWarnings()

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

stats.toJson(options)

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

stats.toJson('minimal');

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(
  {
    // ...
  },
  (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) => {
    process.stdout.write(stats.toString() + '\n');
  }
);

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

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

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

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

const webpack = require('webpack');

webpack(
  {
    // ...
  },
  (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 на memfs для записи файлов в память вместо диска:

const { createFsFromVolume, Volume } = require('memfs');
const webpack = require('webpack');

const fs = createFsFromVolume(new Volume());
const compiler = webpack({
  /* options */
});

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

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