PostCSS Runner 指南

🌙
手机阅读
本文目录结构

PostCSS Runner 指南

PostCSS runner 是一个通过一连串用户定义插件处理 CSS 的工具;例如,[postcss-cli] 或 [gulp-postcss]。 这些规则对于任何此类 runner 都是强制性的。

对于单插件工具,如 [gulp-autoprefixer],这些规则不是强制性的,但非常建议使用。

另参考 ClojureWerkz’s recommendations 了解开源项目。

1. API

1.1. 在插件参数中接受函数

如果你的 runner 使用配置文件,它必须用 JavaScript 编写,这样它可以支持接受函数的插件,例如 postcss-assets:

module.exports = [
  require('postcss-assets')({
    cachebuster: function (file) {
      return fs.statSync(file).mtime.getTime().toString(16)
    }
  })
]

2. 处理

2.1. 设置 fromto 处理选项

为了保证 PostCSS 生成源映射并更好地显示的语法错误,runner 必须指定 fromto 选项。

如果你的 runner 不用处理写入磁盘(例如,gulp 转换)任务,您将两个选项设置成指向同一个文件:

processor.process({ from: file.path, to: file.path })

2.2. 请只使用异步 API

PostCSS runner 必须只使用异步 API。同步 API 仅用于调试,速度更慢,并且无法与异步插件一同工作。

processor.process(opts).then(result => {
  // processing is finished
});

2.3. 请只使用公开的 PostCSS API

PostCSS 插件不能依赖于未记录的属性或方法,在任何次要版本中可能会有所变化。公共 API 在 API docs 中描述。

3. Output

3.1. 不要为 CssSyntaxError 显示堆栈

PostCSS runner 不应为 CSS 语法错误显示堆栈,因为 runner 会被不熟悉 JavaScript 的开发人员使用。 相反,要优雅地处理这样的错误:

processor.process(opts).catch(error => {
  if (error.name === 'CssSyntaxError') {
    process.stderr.write(error.message + error.showSourceCode())
  } else {
    throw error
  }
})

3.2. 显示 result.warnings()

PostCSS runner 必须通过 result.warnings() 输出警告:

result.warnings().forEach(warn => {
  process.stderr.write(warn.toString())
})

另参阅 postcss-log-warningspostcss-messages 插件。

3.3. 允许用户将源码映射写入不同的文件

PostCSS 默认情况下会在生成的文件中内联源码映射;然而,PostCSS runner 必须提供将源码映射保存到其它文件的选项 文件:

if (result.map) {
  fs.writeFile(opts.to + '.map', result.map.toString())
}

4. 文档

4.1. 用英文给你的 runner 写文档

PostCSS runner 必须用英文写好 “README.md”。不要害怕你的英语技能,因为开源社区将会修复你的错误。

当然,也欢迎你用其它语言写文档,但请恰当地对文件全名(比如:README.ja.md)

4.2. 维护一个变更日志

PPostCSS runner 必须在一个单独的文件里,例如 CHANGELOG.md, History.md, 或 GitHub Releases 描述它们所有的变更。访问 Keep A Changelog 获取更多有关如何写变更日志的信息。

当然,你应该使用 SemVer 描述版本号。

4.3. 在 package.json 包含 postcss-runner 关键词

将 PostCSS runner 写成 npm 类库必须在 package.json 中包含 postcss-runner 关键词。这个特别的关键词将对 PostCSS 生态的反馈非常有用。

那些没被发布到 npm 平台的 runner,这个不是强制的,但建议采纳如果 runner 格式能包括该关键词。

AXIHE / 精选资源

浏览全部教程

面试题

学习网站

前端培训
自己甄别

前端书籍

关于朱安邦

我叫 朱安邦,阿西河的站长,在杭州。

以前是一名平面设计师,后来开始接接触前端开发,主要研究前端技术中的JS方向。

业余时间我喜欢分享和交流自己的技术,欢迎大家关注我的 Bilibili

关注我: Github / 知乎

于2021年离开前端领域,目前重心放在研究区块链上面了

我叫朱安邦,阿西河的站长

目前在杭州从事区块链周边的开发工作,机械专业,以前从事平面设计工作。

2014年底脱产在老家自学6个月的前端技术,自学期间几乎从未出过家门,最终找到了满意的前端工作。更多>

于2021年离开前端领域,目前从事区块链方面工作了