ZetCode

Gulp HTML minify

last modified November 15, 2026

In this article we minify HTML files with Gulp 5. We use the gulp-html-minifier-terser plugin to collapse whitespace, remove comments and redundant attributes, and minify inline CSS and JavaScript.

HTML minification

A browser does not need the indentation, the line breaks or the comments of an HTML file. Removing them makes the file smaller, so it downloads faster. HTML is less sensitive to whitespace than source code, but not completely: whitespace between inline elements is significant, and the content of pre and textarea elements must stay as it is. A good minifier knows these rules.

The classic plugin is gulp-htmlmin. It is based on html-minifier, which is not maintained, and npm audit reports a high severity ReDoS vulnerability in it with no fix available. The gulp-html-minifier-terser plugin has the same API but uses the maintained html-minifier-terser fork, so we use it in this tutorial. Like gulp-terser in the Gulp Terser tutorial, it also minifies the JavaScript embedded in the page.

Installing the project

We create a project and install Gulp and the plugin.

$ mkdir gulp-htmlmin
$ cd gulp-htmlmin
$ npm init -y
$ npm i -D gulp gulp-html-minifier-terser
$ mkdir src

The example page

The source page has comments, indentation, a stylesheet with a redundant type attribute, inline CSS and JavaScript, boolean attributes written in the long form, and a pre element whose layout has to be kept.

src/index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Home page</title>
    <!-- main stylesheet -->
    <link rel="stylesheet" type="text/css" href="style.css">
    <style>
        body { margin: 0; }
    </style>
</head>
<body>

    <!-- page header -->
    <h1 class="title">  Welcome  </h1>

    <p>
        This is a   page with    extra
        whitespace.
    </p>

    <input type="checkbox" checked="checked" disabled="disabled">

    <pre>
keep    this
    layout
    </pre>

    <script type="text/javascript">
        // greet the user
        const msg = 'Hello';
        console.log(msg);
    </script>
</body>
</html>

The file has 657 bytes. The plugin accepts the same options as html-minifier-terser; all the optimizations are off by default and we turn on the ones that we need.

The gulpfile

The gulpfile has three tasks that minify the same page with different options.

gulpfile.mjs
import { src, dest } from 'gulp';
import htmlmin from 'gulp-html-minifier-terser';

export function basic() {

    return src('src/*.html')
        .pipe(htmlmin({ collapseWhitespace: true }))
        .pipe(dest('dist/basic'));
}

export function full() {

    return src('src/*.html')
        .pipe(htmlmin({
            collapseWhitespace: true,
            removeComments: true,
            removeRedundantAttributes: true,
            removeScriptTypeAttributes: true,
            removeStyleLinkTypeAttributes: true,
            collapseBooleanAttributes: true,
            minifyCSS: true,
            minifyJS: true
        }))
        .pipe(dest('dist/full'));
}

export function conservative() {

    return src('src/*.html')
        .pipe(htmlmin({
            collapseWhitespace: true,
            conservativeCollapse: true,
            removeComments: true
        }))
        .pipe(dest('dist/conservative'));
}

The package is an ES module, so the gulpfile is gulpfile.mjs, as in the ESM gulpfile tutorial.

Collapsing whitespace

The collapseWhitespace option removes the whitespace between tags and reduces runs of whitespace in text to a single space. The basic task uses only this option.

return src('src/*.html')
    .pipe(htmlmin({ collapseWhitespace: true }))
    .pipe(dest('dist/basic'));

The result is one line. The text of the paragraph is reduced to single spaces, but the pre element is untouched. The comments, the type attributes and the long form of the boolean attributes are still there, and the inline CSS and JavaScript are only trimmed.

$ npx gulp basic --silent
$ cat dist/basic/index.html
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>Home page</title><!-- main stylesheet --><link rel="stylesheet" type="text/css" href="style.css"><style>body { margin: 0; }</style></head><body><!-- page header --><h1 class="title">Welcome</h1><p>This is a page with extra whitespace.</p><input type="checkbox" checked="checked" disabled="disabled"><pre>
keep    this
    layout
    </pre><script type="text/javascript">// greet the user
        const msg = 'Hello';
        console.log(msg);</script></body></html>

Removing comments and redundant attributes

The full task turns on more options. The removeComments option deletes HTML comments. The removeRedundantAttributes option removes attributes that equal the default value, and removeScriptTypeAttributes and removeStyleLinkTypeAttributes remove the type attributes that are no longer needed in HTML5. The collapseBooleanAttributes option turns checked="checked" into checked.

.pipe(htmlmin({
    collapseWhitespace: true,
    removeComments: true,
    removeRedundantAttributes: true,
    removeScriptTypeAttributes: true,
    removeStyleLinkTypeAttributes: true,
    collapseBooleanAttributes: true,
    minifyCSS: true,
    minifyJS: true
}))

The minifyCSS and minifyJS options minify the content of the style element and of the script element; the JavaScript is processed by Terser, so the comment is removed and the quotes are normalized. The 657 bytes shrank to 384, and the pre element is still intact. Note that these options do not rename variables in the script.

$ npx gulp full --silent
$ cat dist/full/index.html
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>Home page</title><link rel="stylesheet" href="style.css"><style>body{margin:0}</style></head><body><h1 class="title">Welcome</h1><p>This is a page with extra whitespace.</p><input type="checkbox" checked disabled><pre>
keep    this
    layout
    </pre><script>const msg="Hello";console.log(msg)</script></body></html>
$ wc -c src/index.html dist/*/index.html
 657 src/index.html
 531 dist/basic/index.html
 384 dist/full/index.html
1572 total

Conservative whitespace collapsing

Removing all whitespace between tags can change the layout when elements are displayed inline: two links that are separated by a space would be glued together. The conservativeCollapse option always keeps one space where whitespace was, which is safe in every case.

.pipe(htmlmin({
    collapseWhitespace: true,
    conservativeCollapse: true,
    removeComments: true
}))

Compare the result with the basic task: the tags are now separated by single spaces, which makes the file a little larger but never changes how the page looks. A related option is preserveLineBreaks, which keeps one line break instead of a space. Use ignoreCustomFragments if the HTML contains template tags such as <?php ... ?>.

$ npx gulp conservative --silent
$ cat dist/conservative/index.html
<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Home page</title> <link rel="stylesheet" type="text/css" href="style.css"> <style> body { margin: 0; } </style> </head> <body> <h1 class="title"> Welcome </h1> <p> This is a page with extra whitespace. </p> <input type="checkbox" checked="checked" disabled="disabled"> <pre>
keep    this
    layout
    </pre> <script type="text/javascript"> // greet the user
        const msg = 'Hello';
        console.log(msg); </script> </body> </html> 

Minifying in a build

In a complete build the HTML task runs next to the style and script tasks, for example with parallel from the Gulp series and parallel tutorial, and the output directory is deleted first, as in the Gulp clean tutorial. The HTML files can also be assembled from partials before they are minified; that is the topic of the Gulp file include tutorial.

Source

gulp-html-minifier-terser on npm, html-minifier-terser, Gulp src

In this article we have minified HTML with Gulp 5: we collapsed whitespace, removed comments and redundant attributes, minified inline CSS and JavaScript, and compared aggressive and conservative whitespace handling. See also the Gulp clean-css 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.