ZetCode

Gulp PostCSS

last modified November 15, 2026

In this article we process CSS with Gulp 5 and PostCSS. We add vendor prefixes with Autoprefixer, minify the result with cssnano, choose the target browsers with a Browserslist query, and keep the plugin list in a postcss.config.cjs file.

PostCSS

PostCSS is a tool that parses CSS into a tree, lets plugins change the tree, and writes the CSS back. It does nothing by itself; all the work is done by plugins. Two of them are used in almost every project. Autoprefixer adds vendor prefixes such as -webkit- and -moz- only where the target browsers need them. cssnano minifies the stylesheet. The gulp-postcss plugin runs PostCSS inside a Gulp pipeline. The Gulp basics are in the Gulp getting started tutorial, and a different way to minify CSS is shown in the Gulp clean-css tutorial.

Installing the project

We create a project and install Gulp, gulp-postcss, PostCSS itself, and the two plugins. PostCSS is a peer dependency of gulp-postcss, so we must install it ourselves.

$ mkdir gulp-postcss
$ cd gulp-postcss
$ npm init -y
$ npm i -D gulp gulp-postcss postcss autoprefixer cssnano
$ mkdir -p src/css

The example project

The stylesheet uses a few properties that still need prefixes in some browsers: user-select, appearance, backdrop-filter, position: sticky and the ::placeholder pseudo-element.

src/css/style.css
/* page layout */
body {
    font-family: system-ui, sans-serif;
    margin: 0;
}

.card {
    display: flex;
    user-select: none;
    backdrop-filter: blur(4px);
    appearance: none;
}

.card input::placeholder {
    color: gray;
}

.header {
    position: sticky;
    top: 0;
}

.gallery {
    display: grid;
    grid-template-columns: repeat(3, 1fr);
    gap: 1rem;
}

The file is plain CSS with a comment on the first line. We do not write any prefixes ourselves; that is the job of Autoprefixer.

The target browsers are described by a Browserslist query. The best place for it is the browserslist key of package.json, because other tools, such as Babel, read it too. We use the defaults query.

package.json
{
  "name": "gulp-postcss",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "autoprefixer": "^10.6.2",
    "cssnano": "^8.0.10",
    "gulp": "^5.0.1",
    "gulp-postcss": "^10.0.0",
    "postcss": "^8.5.33"
  },
  "browserslist": [
    "defaults"
  ]
}

The defaults query is a shortcut for the browsers that are used by more than 0.5 % of people, the last two versions of every browser, Firefox ESR, and browsers that are not dead. The npx browserslist command prints the list that a query selects; we show the first lines.

$ npx browserslist | head -8
and_chr 157
and_ff 160
and_qq 14.9
and_uc 15.5
android 157
chrome 157
chrome 156
chrome 155
node:events:497
      throw er; // Unhandled 'error' event
      ^

Error: write EPIPE
    at afterWriteDispatched (node:internal/stream_base_commons:159:15)
    at writeGeneric (node:internal/stream_base_commons:150:3)
    at Socket._writeGeneric (node:net:966:11)
    at Socket._write (node:net:978:8)
    at writeOrBuffer (node:internal/streams/writable:572:12)
    at _write (node:internal/streams/writable:501:10)
    at Writable.write (node:internal/streams/writable:510:10)
    at ~/Documents/prog/js/gulp-postcss/node_modules/browserslist/cli.js:108:22
    at Array.forEach (<anonymous>)
    at Object.<anonymous> (~/Documents/prog/js/gulp-postcss/node_modules/browserslist/cli.js:107:14)
Emitted 'error' event on Socket instance at:
    at emitErrorNT (node:internal/streams/destroy:170:8)
    at emitErrorCloseNT (node:internal/streams/destroy:129:3)
    at process.processTicksAndRejections (node:internal/process/task_queues:90:21) {
  errno: -32,
  code: 'EPIPE',
  syscall: 'write'
}

Node.js v22.19.0
$ npx browserslist | wc -l
37

Adding vendor prefixes

The gulpfile exports three tasks. We start with prefix, which runs Autoprefixer only.

gulpfile.mjs
import { src, dest } from 'gulp';
import postcss from 'gulp-postcss';
import autoprefixer from 'autoprefixer';
import cssnano from 'cssnano';

export function prefix() {

    return src('src/css/*.css')
        .pipe(postcss([autoprefixer()]))
        .pipe(dest('dist'));
}

export function minify() {

    return src('src/css/*.css')
        .pipe(postcss([autoprefixer(), cssnano()]))
        .pipe(dest('dist/min'));
}

export function config() {

    return src('src/css/*.css', { sourcemaps: true })
        .pipe(postcss())
        .pipe(dest('dist/config', { sourcemaps: '.' }));
}

The postcss function takes an array of PostCSS plugins and applies them to every file of the stream. The prefix task reads the stylesheet, runs autoprefixer(), and writes the result to dist. The minify and config tasks are explained below.

We run the task and print the result. Autoprefixer added the -webkit- and -moz- variants of user-select and appearance, and the ::-moz-placeholder selector, and aligned the declarations. It left backdrop-filter and position: sticky alone, because the browsers in the defaults query support them unprefixed.

$ npx gulp prefix
[13:27:12] Using gulpfile ~/Documents/prog/js/gulp-postcss/gulpfile.mjs
[13:27:12] Starting 'prefix'...
[13:27:12] Finished 'prefix' after 39 ms
$ cat dist/style.css
/* page layout */
body {
    font-family: system-ui, sans-serif;
    margin: 0;
}

.card {
    display: flex;
    -webkit-user-select: none;
       -moz-user-select: none;
            user-select: none;
    backdrop-filter: blur(4px);
    -webkit-appearance: none;
       -moz-appearance: none;
            appearance: none;
}

.card input::-moz-placeholder {
    color: gray;
}

.card input::placeholder {
    color: gray;
}

.header {
    position: sticky;
    top: 0;
}

.gallery {
    display: grid;
    grid-template-columns: repeat(3, 1fr);
    gap: 1rem;
}

Choosing the target browsers

Autoprefixer follows the query. To see how, we override it with the BROWSERSLIST environment variable and ask for old Safari and Chrome versions. We print only the lines that contain a prefix. Now backdrop-filter and position: sticky get their -webkit- versions too, and the placeholder uses the -webkit-input-placeholder selector. A narrower query gives a smaller stylesheet; a broader one a bigger and safer one.

$ BROWSERSLIST="Safari >= 10, iOS >= 10, Chrome >= 60, Firefox >= 55" npx gulp prefix --silent
$ grep -E "webkit|moz" dist/style.css
    -webkit-user-select: none;
       -moz-user-select: none;
    -webkit-backdrop-filter: blur(4px);
    -webkit-appearance: none;
       -moz-appearance: none;
.card input::-webkit-input-placeholder {
    position: -webkit-sticky;

Minifying with cssnano

The minify task adds cssnano() after Autoprefixer. The order matters: cssnano should run last, so it also minifies the prefixed declarations.

return src('src/css/*.css')
    .pipe(postcss([autoprefixer(), cssnano()]))
    .pipe(dest('dist/min'));

The result is a single line without comments and whitespace. The source has 374 bytes and the minified file 391, although it contains all the added prefixes.

$ npx gulp minify
[13:27:13] Using gulpfile ~/Documents/prog/js/gulp-postcss/gulpfile.mjs
[13:27:13] Starting 'minify'...
[13:27:13] Finished 'minify' after 56 ms
$ cat dist/min/style.css
body{font-family:system-ui,sans-serif;margin:0}.card{display:flex;-webkit-user-select:none;-moz-user-select:none;user-select:none;backdrop-filter:blur(4px);-webkit-appearance:none;-moz-appearance:none;appearance:none}.card input::-moz-placeholder{color:gray}.card input::placeholder{color:gray}.header{position:sticky;top:0}.gallery{display:grid;grid-template-columns:repeat(3,1fr);gap:1rem}
$ wc -c src/css/style.css dist/min/style.css
374 src/css/style.css
391 dist/min/style.css
765 total

The postcss.config.cjs file

When we call postcss() without arguments, gulp-postcss looks for a configuration file and loads the plugins from it. It uses the same file as the PostCSS command line tool and other bundlers, so the plugin list lives in one place. We use the .cjs extension, which works in both CommonJS and ES module projects.

postcss.config.cjs
module.exports = {
    plugins: [
        require('autoprefixer'),
        require('cssnano')({ preset: 'default' })
    ]
};

The file exports an object with a plugins list. cssnano receives its options as an object; here we select the default preset explicitly. We also ask for a source map, which we describe in the next section.

Source maps

Minified CSS is hard to debug. Gulp 5 can create a source map without an extra plugin: sourcemaps: true in src starts the tracking, and sourcemaps: '.' in dest writes the map into a separate file next to the stylesheet. The Gulp source maps tutorial covers the option in detail.

return src('src/css/*.css', { sourcemaps: true })
    .pipe(postcss())
    .pipe(dest('dist/config', { sourcemaps: '.' }));

The task writes style.css and style.css.map; the stylesheet ends with the sourceMappingURL comment that points to the map. Browser developer tools use it to show the original rules.

$ npx gulp config
[13:27:14] Using gulpfile ~/Documents/prog/js/gulp-postcss/gulpfile.mjs
[13:27:14] Starting 'config'...
[13:27:14] Finished 'config' after 84 ms
$ ls dist/config
style.css
style.css.map
$ tail -c 60 dist/config/style.css
epeat(3,1fr);gap:1rem}/*# sourceMappingURL=style.css.map */

Source

PostCSS, Autoprefixer, cssnano, Browserslist, gulp-postcss on npm

In this article we have processed CSS with PostCSS in Gulp 5: we added vendor prefixes with Autoprefixer, selected target browsers with Browserslist, minified the result with cssnano, and moved the plugins into postcss.config.cjs. See also the Gulp Sass and Gulp src and dest tutorials.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Gulp tutorials.