Gulp clean-css
last modified November 15, 2026
In this article we minify CSS with Gulp 5 and the gulp-clean-css
plugin. We compare the level 1 and level 2 optimizations, format the output, remove
comments, and read the statistics that the plugin reports.
The gulp-clean-css plugin
clean-css is a fast CSS minifier written in JavaScript. The
gulp-clean-css plugin connects it to Gulp. Unlike
PostCSS with cssnano, it is a single package with its own
options and no plugin system. It works in two levels. Level 1 is the default; it makes
safe changes inside single rules: it removes whitespace and comments, shortens colors and
values, and drops redundant units. Level 2 restructures the stylesheet: it merges
rules with the same selectors or the same declarations, and combines longhand properties
into shorthands.
Installing the project
We create a project and install Gulp and the plugin.
$ mkdir gulp-cleancss $ cd gulp-cleancss $ npm init -y $ npm i -D gulp gulp-clean-css $ mkdir src
The example project
The stylesheet contains what a real one accumulates over time: four margins that could be
one, two rules with the same declarations, a rule split into several parts, long colors, and
a license comment that starts with /*!.
/*! Site styles v1.0 */
/* layout */
.container {
margin-top: 10px;
margin-right: 20px;
margin-bottom: 10px;
margin-left: 20px;
color: #ff0000;
background: transparent;
}
.box {
color: #ff0000;
padding: 0px;
font-weight: bold;
}
.panel {
color: #ff0000;
padding: 0px;
font-weight: bold;
}
.button { border: 1px solid #cccccc; }
.button { border-radius: 4px; }
.button:hover { border-color: #000000; }
@media (min-width: 600px) {
.box { width: 50%; }
}
The file has 508 bytes. The gulpfile has one task for every variant that we try; each writes into its own directory, so we can compare the results.
import { src, dest } from 'gulp';
import cleanCSS from 'gulp-clean-css';
export function level1() {
return src('src/*.css')
.pipe(cleanCSS())
.pipe(dest('dist/level1'));
}
export function level2() {
return src('src/*.css')
.pipe(cleanCSS({ level: 2 }))
.pipe(dest('dist/level2'));
}
export function stats() {
return src('src/*.css')
.pipe(cleanCSS({ level: 2 }, (details) => {
console.log(`${details.name}: ${details.stats.originalSize} -> ${details.stats.minifiedSize} bytes`);
console.log(`efficiency: ${(details.stats.efficiency * 100).toFixed(1)} %`);
}))
.pipe(dest('dist/stats'));
}
export function beautify() {
return src('src/*.css')
.pipe(cleanCSS({ level: 2, format: 'beautify' }))
.pipe(dest('dist/beautify'));
}
export function noComments() {
return src('src/*.css')
.pipe(cleanCSS({ level: { 1: { specialComments: 0 }, 2: {} } }))
.pipe(dest('dist/nocomments'));
}
All tasks read the same stylesheet and differ in the options passed to
cleanCSS. The stats task also passes a callback, which we
describe later.
Level 1 optimizations
The level1 task calls cleanCSS() without options. The result is a
single line. Whitespace and the ordinary comment are gone, but the
/*! comment is kept. The colors are shorter: #ff0000 became
red and #cccccc became #ccc. The value
0px is now 0, bold is 700, and
transparent in the background shorthand became 0 0.
The structure is unchanged: the four margins, the duplicated rules and the split
.button rules are all still there.
$ npx gulp level1 --silent
$ cat dist/level1/style.css
/*! Site styles v1.0 */.container{margin-top:10px;margin-right:20px;margin-bottom:10px;margin-left:20px;color:red;background:0 0}.box{color:red;padding:0;font-weight:700}.panel{color:red;padding:0;font-weight:700}.button{border:1px solid #ccc}.button{border-radius:4px}.button:hover{border-color:#000}@media (min-width:600px){.box{width:50%}}
$ wc -c dist/level1/style.css
342 dist/level1/style.css
Level 2 optimizations
The level2 task passes { level: 2 }. The plugin now rewrites the
stylesheet. The four margins are combined into margin:10px 20px, the
.box and .panel rules with identical declarations are merged into one
rule with a selector list, and the two .button rules become one. The output is
about half of the input.
return src('src/*.css')
.pipe(cleanCSS({ level: 2 }))
.pipe(dest('dist/level2'));
Level 2 may reorder rules, so it can change the result of a cascade that depends on the order of rules with the same specificity. We should compare the page before and after, and fall back to level 1 when something breaks.
$ npx gulp level2 --silent
$ cat dist/level2/style.css
/*! Site styles v1.0 */.container{color:red;background:0 0;margin:10px 20px}.box,.panel{color:red;padding:0;font-weight:700}.button{border:1px solid #ccc;border-radius:4px}.button:hover{border-color:#000}@media (min-width:600px){.box{width:50%}}
$ wc -c dist/level2/style.css
245 dist/level2/style.css
Output format
For debugging we do not always want one line. The format option controls
the layout of the output; the beautify value indents the rules and puts every
declaration on its own line. The optimizations still apply.
cleanCSS({ level: 2, format: 'beautify' })
The output is similar to a formatted version of the level 2 result.
$ npx gulp beautify --silent
$ cat dist/beautify/style.css
/*! Site styles v1.0 */
.container {
color: red;
background: 0 0;
margin: 10px 20px
}
.box,
.panel {
color: red;
padding: 0;
font-weight: 700
}
.button {
border: 1px solid #ccc;
border-radius: 4px
}
.button:hover {
border-color: #000
}
@media (min-width:600px) {
.box {
width: 50%
}
}
Removing comments
The /*! comment is meant for license texts, so level 1 keeps it. The
specialComments option changes this: 0 removes all of them,
1 keeps the first one, and 'all' keeps all. We set it inside the level 1
options; the empty 2: {} enables level 2 with its default settings.
cleanCSS({ level: { 1: { specialComments: 0 }, 2: {} } })
The license comment is gone and the stylesheet starts with the first rule.
$ npx gulp noComments --silent
$ cat dist/nocomments/style.css
.container{color:red;background:0 0;margin:10px 20px}.box,.panel{color:red;padding:0;font-weight:700}.button{border:1px solid #ccc;border-radius:4px}.button:hover{border-color:#000}@media (min-width:600px){.box{width:50%}}
Statistics
The second argument of cleanCSS is a callback that receives a details
object for each processed file. It has the name and the stats of the
run: the original and minified size in bytes, the time, and the efficiency, a number between 0
and 1. We use it to log how much each file shrank. The name has a leading slash, as in
/style.css.
cleanCSS({ level: 2 }, (details) => {
console.log(`${details.name}: ${details.stats.originalSize} -> ${details.stats.minifiedSize} bytes`);
console.log(`efficiency: ${(details.stats.efficiency * 100).toFixed(1)} %`);
})
For our stylesheet level 2 saves almost half of the bytes.
$ npx gulp stats [13:27:52] Using gulpfile ~/Documents/prog/js/gulp-cleancss/gulpfile.mjs [13:27:52] Starting 'stats'... /style.css: 508 -> 245 bytes efficiency: 51.8 % [13:27:52] Finished 'stats' after 29 ms
Source
clean-css, gulp-clean-css on npm
In this article we have minified CSS with gulp-clean-css: we compared the level 1 and
level 2 optimizations, formatted the output, removed license comments, and logged the statistics. See also the Gulp PostCSS and Gulp Terser tutorials.
Author
List all Gulp tutorials.