Node.js API

webpack提供了同Node.js运行时通讯的Node.js API。
Node.js API在需要自定义开发或构建流程的场景中很有用。
因为所有的日志输出及错误处理都必须人工处理，没办法自动处理。
webpack只负责编译功能。因为这个原因stats配置在webpack()调用中不起任何作用。

Installation

如果想使用Node.js API，需要首先安装webpack。

npm install webpack --save-dev

在Node.js代码中引入webpack 模块。

const webpack = require("webpack");

// Or if you prefer ES2015:
import webpack from "webpack";

webpack()

导入的webpack方法可以传递Configuration Object并在提供回调函数的情况下运行webapck compiler。

const webpack = require("webpack");

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

err对象不包含编译错误的相关信息，编译的错误信息需要单独通过
stats.hasErrors()来获取.err对象只包含webpack相关的错误问题，比如缺少某项配置。

Note可以给webpack function传递一个配置数组:

webpack([
  { /* Configuration Object */ },
  { /* Configuration Object */ },
  { /* Configuration Object */ }
], (err, stats) => {
  // ...
});

当有多个配置文件时webpack默认是串行处理的，只有在前一个处理完成后，才会处理后一个。
如果希望webpack并行处理配置项，可以使用parallel-webpack

Compiler Instance

如果不想webpack function中传递回调callback。
webpack function会返回Compiler对象。
该Compiler实例可以用来触发webpack 运行或构建并监控文件改变。
比较像CLIApi。
Compiler实例提供以下方法

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

Run

调用Compiler的run方法，类似上面运行的运行webpack的方法。

const webpack = require("webpack");

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

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

Watching

调用watch方法，触发webpack runner。并会监控文件的改变(类似CLI: webpack --watch).
在webpack监控到改变之后，会重新运行。
该函数会返回一个Watching对象。

//函数声明
//watch(watchOptions,callback)

const webpack = require("webpack");

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

const watching = compiler.watch({
  /* watchOptions */
}, (err, stats) => {
  // Print watch/build result here...
  console.log(stats);
});

Watching的配置项详情参见配置项详情

Close Watching

watch方法返回的Watching对象提供了.close(callback)方法。
调用该方法会终止对文件的监控

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

已关闭的或被设位invalidated的watcher不容许再次被运行

Invalidate Watching

手动指定本次编译被废弃，但仍然对文件进行监控。

watching.invalidate(() => {
  console.warn("Invalidated.");
});

Stats Object

stats对象是webpack回调函数的第二个参数。
主要用来显示代码编译过程中的相关信息，主要包括

Errors and Warnings(if any)
Timings
Module and Chunk Information
etc.
webpack CLI使用这些信息，
将格式化后的日志打印到console中。
该对象对外提供下面这些方法。

stats.hasErrors

用来检测编译期是否有error产生，返回true或false.

stats.hasWarnings

用来检测编译期是否有warning产生，返回true或false.

stats.toJson

将编译信息作为JSON object返回。options可以是string或object。
使用object可以进行细粒度的配置。

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

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

可用的配置项，参见dev_server中关于stats的配置。
使用该配置打印的日志示例

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
  }));
});

Error Handling

为了比较好的处理error，一般需要统计三种类型的error。

严重的webpack错误(错误的webpack配置 .etc)
编译错误(缺modules，语法错误 .etc)
编译警告

示例:

const webpack = require("webpack");

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

  const info = stats.toJson();
  //处理代码编译中产生的error
  if (stats.hasErrors()) {
    console.error(info.errors);
  }
  //处理代码编译中产生的warning
  if (stats.hasWarnings()) {
    console.warn(info.warnings)
  }

  // Log result...
});

Compiling to Memory

webpack将输出文件写到指定的磁盘文件中，如果希望改变输出文件的位置，
比如输出到内存，webDAV等，可以通过对Compiler的outputFileSystem配置进行设置。

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("...");
});