A Post\+CSS runner is a tool that processes CSS through a user-\/defined list of plugins; for example, \href{https://github.com/postcss/postcss-cli}{\texttt{ {\ttfamily postcss-\/cli}}} or~\href{https://github.com/w0rm/gulp-postcss}{\texttt{ {\ttfamily gulp‑postcss}}}. These rules are mandatory for any such runners.

For single-\/plugin tools, like \href{https://github.com/sindresorhus/gulp-autoprefixer}{\texttt{ {\ttfamily gulp-\/autoprefixer}}}, these rules are not mandatory but are highly recommended.

See also \href{http://blog.clojurewerkz.org/blog/2013/04/20/how-to-make-your-open-source-project-really-awesome/}{\texttt{ Clojure\+Werkz’s recommendations}} for open source projects.\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20705}{}\doxysection{1. API}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20705}
\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20706}{}\doxysubsection{1.\+1. Accept functions in plugin parameters}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20706}
If your runner uses a config file, it must be written in Java\+Script, so that it can support plugins which accept a function, such as \mbox{[}{\ttfamily postcss-\/assets}\mbox{]}\+:


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

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20707}{}\doxysection{2. Processing}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20707}
\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20708}{}\doxysubsection{2.\+1. Set $<$tt$>$from$<$/tt$>$ and $<$tt$>$to$<$/tt$>$ processing options}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20708}
To ensure that Post\+CSS generates source maps and displays better syntax errors, runners must specify the {\ttfamily from} and {\ttfamily 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\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{processor.process(\{ from: file.path, to: file.path \}) }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20709}{}\doxysubsection{2.\+2. Use only the asynchronous API}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20709}
Post\+CSS runners must use only the asynchronous API. The synchronous API is provided only for debugging, is slower, and can’t work with asynchronous plugins.


\begin{DoxyCode}{0}
\DoxyCodeLine{processor.process(opts).then(result => \{}
\DoxyCodeLine{  // processing is finished}
\DoxyCodeLine{\}); }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20710}{}\doxysubsection{2.\+3. Use only the public Post\+CSS API}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20710}
Post\+CSS 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 \href{http://api.postcss.org/}{\texttt{ API docs}}.\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20711}{}\doxysection{3. Output}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20711}
\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20712}{}\doxysubsection{3.\+1. Don’t show JS stack for $<$tt$>$\+Css\+Syntax\+Error$<$/tt$>$}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20712}
Post\+CSS runners must not show a stack trace for CSS syntax errors, as the runner can be used by developers who~are~not familiar with Java\+Script. Instead, handle such errors gracefully\+:


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

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20713}{}\doxysubsection{3.\+2. Display $<$tt$>$result.\+warnings()$<$/tt$>$}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20713}
Post\+CSS runners must output warnings from {\ttfamily result.\+warnings()}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{result.warnings().forEach(warn => \{}
\DoxyCodeLine{  process.stderr.write(warn.toString())}
\DoxyCodeLine{\}) }

\end{DoxyCode}


See also \href{https://github.com/davidtheclark/postcss-log-warnings}{\texttt{ postcss-\/log-\/warnings}} and \href{https://github.com/postcss/postcss-messages}{\texttt{ postcss-\/messages}} plugins.\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20714}{}\doxysubsection{3.\+3. Allow the user to write source maps to different files}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20714}
Post\+CSS by default will inline source maps in the generated file; however, Post\+CSS runners must provide an option to~save the source map in a different file\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{if (result.map) \{}
\DoxyCodeLine{  fs.writeFile(opts.to + '.map', result.map.toString())}
\DoxyCodeLine{\} }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20715}{}\doxysection{4. Documentation}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20715}
\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20716}{}\doxysubsection{4.\+1. Document your runner in English}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20716}
Post\+CSS runners must have their {\ttfamily README.\+md} wrote 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.~{\ttfamily README.\+ja.\+md}).\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20717}{}\doxysubsection{4.\+2. Maintain a changelog}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20717}
Post\+CSS runners must describe changes of all releases in a separate file, such as {\ttfamily Change\+Log.\+md}, {\ttfamily History.\+md}, or~with~\href{https://help.github.com/articles/creating-releases/}{\texttt{ Git\+Hub Releases}}. Visit \href{http://keepachangelog.com/}{\texttt{ Keep A Changelog}} for more information on how to write one of these.

Of course, you should use \href{http://semver.org/}{\texttt{ Sem\+Ver}}.\hypertarget{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20718}{}\doxysubsection{4.\+3. $<$tt$>$postcss-\/runner$<$/tt$>$ keyword in $<$tt$>$package.\+json$<$/tt$>$}\label{md_sfcode_node_modules_postcss_docs_guidelines_runner_autotoc_md20718}
Post\+CSS runners written for npm must have the {\ttfamily postcss-\/runner} keyword in their {\ttfamily package.\+json}. This special keyword will~be useful for feedback about the Post\+CSS ecosystem.

For packages not published to npm, this is not mandatory, but recommended if the package format is allowed to contain keywords. 