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.
/* 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.
{
"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.
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.
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
List all Gulp tutorials.