ZetCode

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 /*!.

src/style.css
/*! 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.

gulpfile.mjs
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

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.