目录

Webpack 2.2 中文文档

如何编写一个 loader?

loader是导出function的节点模块。

当资源应该由此loader转换时,调用此函数。

在简单的情况下,当只有一个loader应用于资源时,调用loader有一个参数:作为字符串的资源文件的内容。

这个loader能够在这个函数的上下文中this中可以访问 [[loader API | loaders]]。

一个同步loader可以通过return来返回这个值。在其他情况下,loader可以通过this.callback(err, values…)函数返回任意数量的值。错误会被传到this.callback函数或者在同步loader中抛出。

这个loader应该返回一个或者两个值。第一个值是JavaScript代码产生的字符串或者缓冲区。第二个可选的值是JavaScript对象的SourceMap。

在复杂的情况下,当多个loaders被链接的时候,只有最后一个loader能够获取资源文件并且只有第一个loader预期返回一个或者两个值(JavaScript和SourceMap)。其它任何loader返回的值会传到之前的loader中。

例子

// 定义loader
module.exports = function(source) {
  return source;
};
// 通过SourceMap支持定义loader
module.exports = function(source, map) {
  this.callback(null, source, map);
};

指南

(按照优先级排序,第一个具有最高的优先级)

  • Loaders应该只做一个任务
  • Loaders能够被链接。为每一步创建loaders,而不是让一个loader马上做所有事情。

这也意味着不必须的话它们不应该转换成JavaScript。

例子:通过应用查询参数来将模板文件渲染成HTML。

我可以写一个能够将源文件编译成模板的loader,执行并且返回一个模板,这个模板能够导出一个包含HTML代码的字符串。这样是不好的。

相反,我应该为这个用例中的每一个任务写入loaders并且应用它们(管道):

  • jade-loader:将模板转换成一个导出一个函数的模块
  • apply-loader:采取一个导出模块函数并且通过应用查询参数来返回原结果。
  • html-loader:采取HTML并且通过导出字符串来导出模块。

产生标准化模块

Loader生成的模块应遵循与常规模块相同的设计原则。

例子:这是一个不好的设计:(非标准化的,全局状态,…)

require("any-template-language-loader!./xyz.atl");

var html = anyTemplateLanguage.render("xyz");

如果可能的话把它标志成可缓存的.

大多数loaders是可以缓存的,因此它们应该把自身标志成可缓存的。

只要在load中调用cacheable。

// 利用cacheable定义loader
module.exports = function(source) {
  this.cacheable();
  return source;
};

不要在运行和模块间保存状态

loader应该和其它编译后的模块相互独立。(除了能够被loader处理的这些问题)

loader应该和相同模块的之前汇编相互独立。

标志依赖

如果loader使用外部资源(比如读文件系统),它们必须说明。这个信息被用来废弃可缓存的loader并且在观察模式下重新编译。

// 在loader中添加header
var path = require("path");
module.exports = function(source) {
  this.cacheable();
  var callback = this.async();
  var headerPath = path.resolve("header.js");
  this.addDependency(headerPath);
  fs.readFile(headerPath, "utf-8", function(err, header) {
    if(err) return callback(err);
    callback(null, header + "\n" + source);
  });
};

解析依赖关系

在很多语言中存在某些机制来规定依赖,比如在css里面使用@import以及url(…)。这些依赖可以通过模块系统来解析。

存在两个选项:

  • 将它们转化成 requires。
  • 使用this.resolve函数来解析路径。

例子1 css-loader:css-loader 将依赖转换成 require,通过使用引入其它样式表(也是通过css-loader来处理)来代替@import以及通过require其它的引用文件来代替url(…)。

例子2 less-loader:less-loader 不能够将@import 转换成 require,因为所有的less文件需要一起编译来跟踪变量和mixins。因此 less-loader 通过一个定制的路径解析逻辑来拓展less编译器。这个定制的逻辑使用this.resolve通过模块系统的配置(别名使用,定制的模块目录,等等)来解析文件。

如果语言只支持相对路径(比如在css中:url(file)总是表示./file),利用~约定来规定模块的引用。

url(file) -> require("./file")
url(~module) -> require("module")

提取共用代码

不生成过多在每个loader中么个模块都会处理的共用代码。在loader中创建一个(运行期)文件并且创建对共用代码的require。

不要嵌入绝对路径

不要将绝对路径放入模块代码中。当项目根路径被移动的时,它们会破坏散列函数。在loader-utils中有stringifyRequest这个方法能够将绝对路径转成相对路径。

例子:

var loaderUtils = require("loader-utils");

return "var runtime = require(" +
  loaderUtils.stringifyRequest(this, "!" + require.resolve("module/runtime")) +
  ");";

使用peerDependencies 来包装library

用开发者能够在package.json里面规定具体的版本。依赖关系应该相对开放从而允许在不需要发布新的loader版本的时候更新library。

"peerDependencies": {
  "library": "^1.3.5"
}

将可编程对象当作query选项

在某些情况下,你的loader需要可编程对象,其函数不能作为query字符串进行字符串化。例如,less-loader 提供了指定LESS-plugins的可能性。在这些情况下,允许loader拓展webpack的options对象来检索特定选项。然而,为了避免名称冲突,重要的是该选项在loader的驼峰npm-name下的命名空间。

示例:

// webpack.config.js
module.exports = {
  ...
  lessLoader: {
    lessPlugins: [
      new LessPluginCleanCSS({advanced: true})
    ]
  }
};

loader还应该允许通过query来指定config-key(比如lessLoader)。 See 讨论 and 案例实现.

上一篇: 下一篇: