1 # PostCSS Plugin Guidelines
3 A PostCSS plugin is a function that receives and, usually,
4 transforms a CSS AST from the PostCSS parser.
6 The rules below are *mandatory* for all PostCSS plugins.
8 See also [ClojureWerkz’s recommendations] for open source projects.
10 [ClojureWerkz’s recommendations]: http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/
14 ### 1.1 Clear name with `postcss-` prefix
16 The plugin’s purpose should be clear just by reading its name.
17 If you wrote a transpiler for CSS 4 Custom Media, `postcss-custom-media`
18 would be a good name. If you wrote a plugin to support mixins,
19 `postcss-mixins` would be a good name.
21 The prefix `postcss-` shows that the plugin is part of the PostCSS ecosystem.
23 This rule is not mandatory for plugins that can run as independent tools,
24 without the user necessarily knowing that it is powered by
25 PostCSS — for example, [cssnext] and [Autoprefixer].
27 [Autoprefixer]: https://github.com/postcss/autoprefixer
28 [cssnext]: http://cssnext.io/
30 ### 1.2. Do one thing, and do it well
32 Do not create multitool plugins. Several small, one-purpose plugins bundled into
33 a plugin pack is usually a better solution.
35 For example, [cssnext] contains many small plugins,
36 one for each W3C specification. And [cssnano] contains a separate plugin
37 for each of its optimization.
39 [cssnext]: http://cssnext.io/
40 [cssnano]: https://github.com/ben-eb/cssnano
42 ### 1.3. Do not use mixins
44 Preprocessors libraries like Compass provide an API with mixins.
46 PostCSS plugins are different.
47 A plugin cannot be just a set of mixins for [postcss-mixins].
49 To achieve your goal, consider transforming valid CSS
50 or using custom at-rules and custom properties.
52 [postcss-mixins]: https://github.com/postcss/postcss-mixins
54 ### 1.4. Create plugin by `postcss.plugin`
56 By wrapping your function in this method,
57 you are hooking into a common plugin API:
60 module.exports = postcss.plugin('plugin-name', function (opts) {
61 return function (root, result) {
69 ### 2.1. Plugin must be tested
71 A CI service like [Travis] is also recommended for testing code in
72 different environments. You should test in (at least) Node.js [active LTS](https://github.com/nodejs/LTS) and current stable version.
74 [Travis]: https://travis-ci.org/
76 ### 2.2. Use asynchronous methods whenever possible
78 For example, use `fs.writeFile` instead of `fs.writeFileSync`:
81 postcss.plugin('plugin-sprite', function (opts) {
82 return function (root, result) {
84 return new Promise(function (resolve, reject) {
85 var sprite = makeSprite();
86 fs.writeFile(opts.file, function (err) {
87 if ( err ) return reject(err);
96 ### 2.3. Set `node.source` for new nodes
98 Every node must have a relevant `source` so PostCSS can generate
99 an accurate source map.
101 So if you add new declaration based on some existing declaration, you should
102 clone the existing declaration in order to save that original `source`.
105 if ( needPrefix(decl.prop) ) {
106 decl.cloneBefore({ prop: '-webkit-' + decl.prop });
110 You can also set `source` directly, copying from some existing node:
113 if ( decl.prop === 'animation' ) {
114 var keyframe = createAnimationByName(decl.value);
115 keyframes.source = decl.source;
116 decl.root().append(keyframes);
120 ### 2.4. Use only the public PostCSS API
122 PostCSS plugins must not rely on undocumented properties or methods,
123 which may be subject to change in any minor release. The public API
124 is described in [API docs].
126 [API docs]: http://api.postcss.org/
130 ### 3.1. Use `node.error` on CSS relevant errors
132 If you have an error because of input CSS (like an unknown name
133 in a mixin plugin) you should use `node.error` to create an error
134 that includes source position:
137 if ( typeof mixins[name] === 'undefined' ) {
138 throw decl.error('Unknown mixin ' + name, { plugin: 'postcss-mixins' });
142 ### 3.2. Use `result.warn` for warnings
144 Do not print warnings with `console.log` or `console.warn`,
145 because some PostCSS runner may not allow console output.
148 if ( outdated(decl.prop) ) {
149 result.warn(decl.prop + ' is outdated', { node: decl });
153 If CSS input is a source of the warning, the plugin must set the `node` option.
157 ### 4.1. Document your plugin in English
159 PostCSS plugins must have their `README.md` written in English. Do not be afraid
160 of your English skills, as the open source community will fix your errors.
162 Of course, you are welcome to write documentation in other languages;
163 just name them appropriately (e.g. `README.ja.md`).
165 ### 4.2. Include input and output examples
167 The plugin's `README.md` must contain example input and output CSS.
168 A clear example is the best way to describe how your plugin works.
170 The first section of the `README.md` is a good place to put examples.
171 See [postcss-opacity](https://github.com/iamvdo/postcss-opacity) for an example.
173 Of course, this guideline does not apply if your plugin does not
176 ### 4.3. Maintain a changelog
178 PostCSS plugins must describe the changes of all their releases
179 in a separate file, such as `CHANGELOG.md`, `History.md`, or [GitHub Releases].
180 Visit [Keep A Changelog] for more information about how to write one of these.
182 Of course, you should be using [SemVer].
184 [Keep A Changelog]: http://keepachangelog.com/
185 [GitHub Releases]: https://help.github.com/articles/creating-releases/
186 [SemVer]: http://semver.org/
188 ### 4.4. Include `postcss-plugin` keyword in `package.json`
190 PostCSS plugins written for npm must have the `postcss-plugin` keyword
191 in their `package.json`. This special keyword will be useful for feedback about
192 the PostCSS ecosystem.
194 For packages not published to npm, this is not mandatory, but is recommended
195 if the package format can contain keywords.