diff options
author | 2020-11-18 23:26:45 +0100 | |
---|---|---|
committer | 2020-11-18 23:26:45 +0100 | |
commit | 81ddf9b700bc48a1f8e472209f080f9c1d9a9b09 (patch) | |
tree | 8b959d50c5a614cbf9fcb346ed556140374d4b6d /node_modules/postcss/docs/guidelines/runner.md | |
parent | 1870f3fdf43707a15fda0f609a021f516f45eb63 (diff) | |
download | website_creator-81ddf9b700bc48a1f8e472209f080f9c1d9a9b09.tar.gz website_creator-81ddf9b700bc48a1f8e472209f080f9c1d9a9b09.tar.bz2 website_creator-81ddf9b700bc48a1f8e472209f080f9c1d9a9b09.zip |
rm node_modules
Diffstat (limited to 'node_modules/postcss/docs/guidelines/runner.md')
-rw-r--r-- | node_modules/postcss/docs/guidelines/runner.md | 143 |
1 files changed, 0 insertions, 143 deletions
diff --git a/node_modules/postcss/docs/guidelines/runner.md b/node_modules/postcss/docs/guidelines/runner.md deleted file mode 100644 index 83f2087..0000000 --- a/node_modules/postcss/docs/guidelines/runner.md +++ /dev/null @@ -1,143 +0,0 @@ -# PostCSS Runner Guidelines - -A PostCSS runner is a tool that processes CSS through a user-defined list -of plugins; for example, [`postcss-cli`] or [`gulp‑postcss`]. -These rules are mandatory for any such runners. - -For single-plugin tools, like [`gulp-autoprefixer`], -these rules are not mandatory but are highly recommended. - -See also [ClojureWerkz’s recommendations] for open source projects. - -[ClojureWerkz’s recommendations]: http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/ -[`gulp-autoprefixer`]: https://github.com/sindresorhus/gulp-autoprefixer -[`gulp‑postcss`]: https://github.com/w0rm/gulp-postcss -[`postcss-cli`]: https://github.com/postcss/postcss-cli - -## 1. API - -### 1.1. Accept functions in plugin parameters - -If your runner uses a config file, it must be written in JavaScript, so that -it can support plugins which accept a function, such as [`postcss-assets`]: - -```js -module.exports = [ - require('postcss-assets')({ - cachebuster: function (file) { - return fs.statSync(file).mtime.getTime().toString(16); - } - }) -]; -``` - -[`postcss-assets`]: https://github.com/borodean/postcss-assets - -## 2. Processing - -### 2.1. Set `from` and `to` processing options - -To ensure that PostCSS generates source maps and displays better syntax errors, -runners must specify the `from` and `to` options. If your runner does not handle -writing to disk (for example, a gulp transform), you should set both options -to point to the same file: - -```js -processor.process({ from: file.path, to: file.path }); -``` - -### 2.2. Use only the asynchronous API - -PostCSS runners must use only the asynchronous API. -The synchronous API is provided only for debugging, is slower, -and can’t work with asynchronous plugins. - -```js -processor.process(opts).then(function (result) { - // processing is finished -}); -``` - -### 2.3. Use only the public PostCSS API - -PostCSS runners must not rely on undocumented properties or methods, -which may be subject to change in any minor release. The public API -is described in [API docs]. - -[API docs]: http://api.postcss.org/ - -## 3. Output - -### 3.1. Don’t show JS stack for `CssSyntaxError` - -PostCSS runners must not show a stack trace for CSS syntax errors, -as the runner can be used by developers who are not familiar with JavaScript. -Instead, handle such errors gracefully: - -```js -processor.process(opts).catch(function (error) { - if ( error.name === 'CssSyntaxError' ) { - process.stderr.write(error.message + error.showSourceCode()); - } else { - throw error; - } -}); -``` - -### 3.2. Display `result.warnings()` - -PostCSS runners must output warnings from `result.warnings()`: - -```js -result.warnings().forEach(function (warn) { - process.stderr.write(warn.toString()); -}); -``` - -See also [postcss-log-warnings] and [postcss-messages] plugins. - -[postcss-log-warnings]: https://github.com/davidtheclark/postcss-log-warnings -[postcss-messages]: https://github.com/postcss/postcss-messages - -### 3.3. Allow the user to write source maps to different files - -PostCSS by default will inline source maps in the generated file; however, -PostCSS runners must provide an option to save the source map in a different -file: - -```js -if ( result.map ) { - fs.writeFile(opts.to + '.map', result.map.toString()); -} -``` - -## 4. Documentation - -### 4.1. Document your runner in English - -PostCSS runners must have their `README.md` written in English. Do not be afraid -of your English skills, as the open source community will fix your errors. - -Of course, you are welcome to write documentation in other languages; -just name them appropriately (e.g. `README.ja.md`). - -### 4.2. Maintain a changelog - -PostCSS runners must describe changes of all releases in a separate file, -such as `ChangeLog.md`, `History.md`, or with [GitHub Releases]. -Visit [Keep A Changelog] for more information on how to write one of these. - -Of course you should use [SemVer]. - -[Keep A Changelog]: http://keepachangelog.com/ -[GitHub Releases]: https://help.github.com/articles/creating-releases/ -[SemVer]: http://semver.org/ - -### 4.3. `postcss-runner` keyword in `package.json` - -PostCSS runners written for npm must have the `postcss-runner` keyword -in their `package.json`. This special keyword will be useful for feedback about -the PostCSS ecosystem. - -For packages not published to npm, this is not mandatory, but recommended -if the package format is allowed to contain keywords. |