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.
<!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.
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
List all Gulp tutorials.