Automate CSS Vendor Prefixes with PostCSS and Autoprefixer

Problem and outcome

You write modern CSS such as display: grid or place-items: center, but older browsers still in your audience ignore those declarations unless they carry vendor prefixes like -webkit- or -moz-. Adding prefixes by hand is tedious and easy to forget when you update a stylesheet.

The useful takeaway is to run your CSS through PostCSS with the Autoprefixer plugin. Autoprefixer reads a Browserslist target list, consults current browser support data, and inserts only the prefixes your selected browsers actually need. You then verify the generated CSS and warnings before shipping it.

Prerequisites

• Node.js and npm installed on your computer or build server.
• A project folder containing at least one CSS file to process.
• Write permission for the folder where the prefixed output will be written.

Install the PostCSS runner, the PostCSS API, and Autoprefixer as development dependencies:

npm install --save-dev postcss postcss-cli autoprefixer

Run this command in your project root. It modifies package.json and creates or updates node_modules.

Configure Browserslist targets

Autoprefixer decides which prefixes to emit based on Browserslist configuration. Without it, the plugin may prefix too much, too little, or not at all. Add a browserslist section to package.json:

{
  "browserslist": [
    "last 2 versions",
    "not dead",
    "> 0.5%"
  ]
}

This means: support the last two versions of each browser, exclude versions with no recent support, and include browsers with more than 0.5% global usage. You can also use a separate .browserslistrc file.

Create the PostCSS configuration

Create postcss.config.js in your project root:

module.exports = {
  plugins: [
    require('autoprefixer')
  ]
};

PostCSS loads this file automatically when you run the CLI. Plugin order matters: put Autoprefixer after any syntax-transforming plugins and before CSS minification, so it does not prefix rules that another plugin removes or changes.

Process the CSS file

Run the PostCSS CLI from your project root:

npx postcss src/styles.css --output dist/styles.css

Replace src/styles.css with your input stylesheet path and dist/styles.css with your desired output path. The command writes a new file, so make sure the output directory exists and that you do not overwrite a file you cannot recover.

If you prefer the Node API instead of the CLI, the equivalent call is:

const postcss = require('postcss');
const autoprefixer = require('autoprefixer');
const fs = require('fs');

const css = fs.readFileSync('src/styles.css', 'utf8');

postcss([autoprefixer])
  .process(css, { from: 'src/styles.css', to: 'dist/styles.css' })
  .then((result) => {
    fs.writeFileSync('dist/styles.css', result.css);
    const warnings = result.warnings();
    if (warnings.length > 0) {
      console.warn('PostCSS warnings:', warnings);
    }
  })
  .catch((error) => {
    console.error('PostCSS processing failed:', error.message);
    process.exit(1);
  });

The from and to options are also required for accurate source maps. Omitting them can break source-map debugging in browser developer tools.

Expected checks

1. Open dist/styles.css and confirm that properties targeted by your browser list now carry prefixes. For example, display: flex may become display: -webkit-flex; display: flex depending on the targeted browser versions.
2. Run the Node API snippet above and confirm result.warnings() returns an empty array or only expected notices. Unexpected warnings often indicate malformed input CSS or an outdated Autoprefixer version.
3. Compare the output against your Browserslist targets. If you target last 2 versions, very old browsers such as Internet Explorer 11 should not receive prefixes unless you explicitly add them to the list.

Limitations

• Autoprefixer adds vendor prefixes only. It does not polyfill unsupported CSS features or transform non-standard syntax into something older browsers understand.
• It cannot fix invalid CSS. A malformed stylesheet throws a CSSSyntaxError and stops processing.
• Results depend on Browserslist data. If your targets are outdated or missing, the prefix output will not match your actual browser support goals.

Practical verification

After processing, search the output for a prefix you expect. For example, if your list includes older Chrome versions, look for -webkit- before border-radius or flex-related declarations. If the property appears without a prefix where one is expected, revisit your Browserslist configuration and confirm Autoprefixer is the last plugin in the pipeline before minification.

Recovery if output is wrong

Because the command writes to dist/styles.css, it changes state. If the generated file is incorrect, restore the previous output from version control or a backup, correct your configuration, and rerun the command. Do not edit the generated file directly; your changes will be lost the next time PostCSS runs.