Guide · Open source
How to use PostCSS: transform CSS with JS plugins
Updated · written with AI from the project's own documentation and checked against our catalogue data
PostCSS is an open-source tool that reads a CSS file, turns it into a tree structure that plugins can inspect and change, and writes the CSS back out. This guide explains how that workflow fits together, how to get the project, which plugins are worth knowing, and when PostCSS is the wrong choice. By the end you will know what PostCSS does and where it fits in a styling workflow.
PostCSSpostcss/postcss · ★ 29k · MIT Install options & downloads Quick start
- 1Check the prerequisite. Make sure Node.js is installed, since the source lists it as the prerequisite.
- 2Get the repository. Clone the project with git clone https://github.com/postcss/postcss, as the README's install step describes.
- 3Pick your plugins. Choose plugins from the list for your goal, such as autoprefixer for vendor prefixes or stylelint for linting.
- 4Configure PostCSS in code. PostCSS is configured and run from code, so set up your plugin list in your build configuration.
- 5Run it on a stylesheet. Pass a CSS file through PostCSS so the plugins can read and change its tree.
- 6Check the output. Review the written CSS to confirm each plugin made the change you wanted.
What PostCSS does and how it works
PostCSS is a tool for transforming styles with JavaScript plugins. It takes a CSS file and provides an API to analyze and modify its rules by transforming them into an Abstract Syntax Tree. Plugins read that tree, change it, and PostCSS then writes the result back out as CSS.
The same pipeline can also handle syntaxes other than plain CSS, as long as a parser exists for them.
- Parse: the CSS file is converted into a tree.
- Transform: one or more plugins read and modify the tree.
- Stringify: PostCSS writes the changed tree back out as CSS.
Get the PostCSS project
The README's install step is to clone the repository from GitHub. The project's prerequisite listed in the source is Node.js, and the install method is a package manager.
The README excerpt provided does not show the full package-manager commands, so check the project's documentation for the exact steps before you set up a build.
- Prerequisite: Node.js
- Install method: package manager
git clone https://github.com/postcss/postcssChoose plugins for the job
Plugins do the actual work. The README says PostCSS has more than 200 plugins and links to a full plugins list. It also highlights a set of favorites grouped by task.
Autoprefixer adds vendor prefixes using data from Can I Use. Stylelint is a modular stylesheet linter. Other groups cover readability, images and fonts, and minification with cssnano.
- Vendor prefixes: autoprefixer
- Use future CSS today: postcss-preset-env
- Linting: stylelint, doiuse (browser support checks)
- Nesting like Sass: postcss-nested
- Minification: cssnano
- Images and fonts: postcss-url, postcss-sprites, font-magician
Use PostCSS with other syntaxes
PostCSS can work with syntaxes beyond CSS. The README lists parsers for SCSS, Sass, Less, and CSS-in-JS, and a parser for indent-based syntax named sugarss.
Be careful with the wording. Most of these parsers let PostCSS read and transform the source, but they do not compile it. The README notes that postcss-scss, postcss-sass and postcss-less do not compile to CSS. The exception it names is postcss-less-engine, which does compile Less using Less.js evaluation.
- postcss-scss: works with SCSS, does not compile it
- postcss-sass: works with Sass, does not compile it
- postcss-less: works with Less, does not compile it
- postcss-less-engine: works with Less and compiles it
- postcss-styled-syntax and postcss-jsx: parse CSS in JavaScript template literals
Handle syntax errors and invalid CSS
When a stylesheet contains syntax errors, the standard parser can stop on them. The README lists postcss-safe-parser as a plugin that finds and fixes CSS syntax errors.
Keep in mind that this is a parser choice, so it affects how the file is read before any other plugin runs. Test your output after switching parsers.
Decide whether PostCSS is right for you
PostCSS is configured and run from code, so it suits developers who are comfortable with a build step. It gives little benefit if you only write plain CSS by hand and have no build step, because most of its value comes from plugins.
If you want a finished stylesheet compiler, the README says PostCSS does not compile SCSS, Sass or Less on its own. Comparable projects named in the source are Sass, Stylus and Lightning CSS.
What people use it for
- Adding vendor prefixes automatically with autoprefixer
- Linting stylesheets and enforcing team rules with stylelint
- Using newer CSS syntax today with postcss-preset-env
- Building your own CSS tooling or plugins on the PostCSS API
- Reading styles inside Markdown code blocks or HTML style tags with dedicated parsers
Frequently asked questions
Is PostCSS free to use?
PostCSS is released under the MIT licence, according to the project summary. Check the repository's licence file for the full terms before you use it in a commercial product.
What do I need to run PostCSS?
The source lists Node.js as the prerequisite. The install method is a package manager, and the README's install step begins by cloning the repository.
Does PostCSS compile Sass or SCSS to CSS?
No, not on its own. The README says the SCSS, Sass and Less parsers do not compile to CSS. The exception it names is postcss-less-engine, which compiles Less.
What is PostCSS used for?
It is used to automate CSS fixes such as vendor prefixes, to lint stylesheets, to support newer CSS syntax, and to inline images. Many well-known tools such as Autoprefixer and Stylelint are built as PostCSS plugins.
What are the alternatives to PostCSS?
The source names Sass, Stylus and Lightning CSS as comparable projects. Sass and Stylus are stylesheet languages with their own compilers, so they solve a different part of the job than PostCSS.
What if my CSS has syntax errors?
The README lists postcss-safe-parser as a plugin that finds and fixes CSS syntax errors. Use it when the standard parser stops on invalid input, then review the output.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
PostCSS suits developers who want to automate CSS fixes, lint stylesheets, or build their own CSS tooling, and who are comfortable configuring a build from code. If you only write plain CSS by hand, or you want a finished compiler for Sass or Less with no setup, pick a tool such as Sass, Stylus or Lightning CSS instead.
Install options & downloads