www.aleph1.co.uk Git - yaffs-website/blob - node_modules/postcss/docs/guidelines/runner.md

   1 # PostCSS Runner Guidelines
   2
   3 A PostCSS runner is a tool that processes CSS through a user-defined list
   4 of plugins; for example, [`postcss-cli`] or [`gulp‑postcss`].
   5 These rules are mandatory for any such runners.
   6
   7 For single-plugin tools, like [`gulp-autoprefixer`],
   8 these rules are not mandatory but are highly recommended.
   9
  10 See also [ClojureWerkz’s recommendations] for open source projects.
  11
  12 [ClojureWerkz’s recommendations]:  http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/
  13 [`gulp-autoprefixer`]: https://github.com/sindresorhus/gulp-autoprefixer
  14 [`gulp‑postcss`]:      https://github.com/w0rm/gulp-postcss
  15 [`postcss-cli`]:       https://github.com/postcss/postcss-cli
  16
  17 ## 1. API
  18
  19 ### 1.1. Accept functions in plugin parameters
  20
  21 If your runner uses a config file, it must be written in JavaScript, so that
  22 it can support plugins which accept a function, such as [`postcss-assets`]:
  23
  24 ```js
  25 module.exports = [
  26     require('postcss-assets')({
  27         cachebuster: function (file) {
  28             return fs.statSync(file).mtime.getTime().toString(16);
  29         }
  30     })
  31 ];
  32 ```
  33
  34 [`postcss-assets`]: https://github.com/borodean/postcss-assets
  35
  36 ## 2. Processing
  37
  38 ### 2.1. Set `from` and `to` processing options
  39
  40 To ensure that PostCSS generates source maps and displays better syntax errors,
  41 runners must specify the `from` and `to` options. If your runner does not handle
  42 writing to disk (for example, a gulp transform), you should set both options
  43 to point to the same file:
  44
  45 ```js
  46 processor.process({ from: file.path, to: file.path });
  47 ```
  48
  49 ### 2.2. Use only the asynchronous API
  50
  51 PostCSS runners must use only the asynchronous API.
  52 The synchronous API is provided only for debugging, is slower,
  53 and can’t work with asynchronous plugins.
  54
  55 ```js
  56 processor.process(opts).then(function (result) {
  57     // processing is finished
  58 });
  59 ```
  60
  61 ### 2.3. Use only the public PostCSS API
  62
  63 PostCSS runners must not rely on undocumented properties or methods,
  64 which may be subject to change in any minor release. The public API
  65 is described in [API docs].
  66
  67 [API docs]: http://api.postcss.org/
  68
  69 ## 3. Output
  70
  71 ### 3.1. Don’t show JS stack for `CssSyntaxError`
  72
  73 PostCSS runners must not show a stack trace for CSS syntax errors,
  74 as the runner can be used by developers who are not familiar with JavaScript.
  75 Instead, handle such errors gracefully:
  76
  77 ```js
  78 processor.process(opts).catch(function (error) {
  79     if ( error.name === 'CssSyntaxError' ) {
  80         process.stderr.write(error.message + error.showSourceCode());
  81     } else {
  82         throw error;
  83     }
  84 });
  85 ```
  86
  87 ### 3.2. Display `result.warnings()`
  88
  89 PostCSS runners must output warnings from `result.warnings()`:
  90
  91 ```js
  92 result.warnings().forEach(function (warn) {
  93     process.stderr.write(warn.toString());
  94 });
  95 ```
  96
  97 See also [postcss-log-warnings] and [postcss-messages] plugins.
  98
  99 [postcss-log-warnings]: https://github.com/davidtheclark/postcss-log-warnings
 100 [postcss-messages]:     https://github.com/postcss/postcss-messages
 101
 102 ### 3.3. Allow the user to write source maps to different files
 103
 104 PostCSS by default will inline source maps in the generated file; however,
 105 PostCSS runners must provide an option to save the source map in a different
 106 file:
 107
 108 ```js
 109 if ( result.map ) {
 110     fs.writeFile(opts.to + '.map', result.map.toString());
 111 }
 112 ```
 113
 114 ## 4. Documentation
 115
 116 ### 4.1. Document your runner in English
 117
 118 PostCSS runners must have their `README.md` written in English. Do not be afraid
 119 of your English skills, as the open source community will fix your errors.
 120
 121 Of course, you are welcome to write documentation in other languages;
 122 just name them appropriately (e.g. `README.ja.md`).
 123
 124 ### 4.2. Maintain a changelog
 125
 126 PostCSS runners must describe changes of all releases in a separate file,
 127 such as `ChangeLog.md`, `History.md`, or with [GitHub Releases].
 128 Visit [Keep A Changelog] for more information on how to write one of these.
 129
 130 Of course you should use [SemVer].
 131
 132 [Keep A Changelog]: http://keepachangelog.com/
 133 [GitHub Releases]:  https://help.github.com/articles/creating-releases/
 134 [SemVer]:           http://semver.org/
 135
 136 ### 4.3. `postcss-runner` keyword in `package.json`
 137
 138 PostCSS runners written for npm must have the `postcss-runner` keyword
 139 in their `package.json`. This special keyword will be useful for feedback about
 140 the PostCSS ecosystem.
 141
 142 For packages not published to npm, this is not mandatory, but recommended
 143 if the package format is allowed to contain keywords.