How to Upgrade From HTML Minifier 4 to 5

Published on Nov 3, 2026, filed under tools, development, html, performance, optimization. (Share this post, e.g., on Mastodon.)

More than seven years after version 4.0.0, HTML Minifier (HM) has a new major release. HM 5 brings everything the HTML Minifier family gained through HTML Minifier Terser and especially HTML Minifier Next—it’s richer in features, easier to use, significantly faster, and actively maintained!

As a lot has changed over the years, here’s a checklist to help you upgrade:

• Node.js: If you run Node.js before 22.13, you need to update Node.js.

• ESM: If you use require('html-minifier'), you need to switch to import { minify } from 'html-minifier' (HM is ESM-only now; in CommonJS, const { minify } = await import('html-minifier') works, too). Imports from within the package (like html-minifier/src/htmlminifier) are no longer supported.

• Async: If you use minify() programmatically, you need to await it (it returns a promise).

• Type attributes: If you use removeScriptTypeAttributes or removeStyleLinkTypeAttributes, you need to replace them with removeDefaultTypeAttributes (--remove-default-type-attributes), which covers both.

• Sorting by class names: If you sort by class names, you need to rename the parameter to use the plural (sortClassNames or --sort-class-names).

• “HTML 5” mode: If you used the html5 option, you should remove it—this mode is always on.

• Conditional Comments: If you use processConditionalComments, you need to remove it. If you remove comments and want to keep Conditional Comments, add patterns for them to ignoreCustomComments, along with the defaults (e.g., --ignore-custom-comments '["^!", "^\\s*#", "^\\[if\\s", "\\[endif\\]$"]')—HM treats Conditional Comments as regular comments.

• Auto-generated tags: If you rely on closing tags that HM 4 inserted (like </p>), you need to enable includeAutoGeneratedTags (includeAutoGeneratedTags: true or --include-auto-generated-tags).

• File extensions: If you use --input-dir on files other than .html, .htm, .shtml, or .shtm, you need to name the file types you use (e.g., --file-ext=html,php), or enable all file types (--file-ext='*').

• CSS minification: If you pass options to minifyCSS, you need to replace them with Lightning CSS options, as HM uses Lightning CSS instead of clean-css (clean-css options are ignored).

• JavaScript minification: If you pass options to minifyJS, check them against Terser’s options, as HM uses Terser instead of UglifyJS (most UglifyJS options carry over). (Alternatively, you can use SWC for JavaScript minification.)

• URL minification: If you pass options to minifyURLs, you need to remove all but site (other relateurl options are ignored).

When given a removed option as a command-line flag, HM stops with an error; in config files and programmatically, it warns and ignores the option.

Depending on your preferences:

• Redundant attributes: If you use removeRedundantAttributes, check that your CSS selectors and scripts don’t depend on default attribute values, as HM now removes many more of them.

• Output: If you care about specific output, compare it with your HM 4 output—HM 5 minifies CSS and JavaScript differently, and covers many more cases (i.e., is more effective).

• New features: HM 5 offers several new features, like presets, SVG minification, config file discovery, and zero-config use (npx html-minifier --zero).

  Tip: Try the comprehensive preset. It gives you excellent minification results and makes configuration super-easy. (You can still turn off and add options you don’t or do like.)

For all details, please check the HTML Minifier changelog as well as the HTML Minifier Next changelog, which documents most of what changed on the way to HM 5. If you run into any problems, please file an issue. (Note that I might need to prioritize my sponsors for help requests.)

Finally, if you like HM as a powerful HTML optimization tool, spread the word and consider supporting the work on it! (Thank you!)

About Me

I’m Jens (long: Jens Oliver Meiert), and I’m an engineering lead, guerrilla philosopher, and indie publisher. I’ve worked as a technical lead and manager at various companies (e.g., Google); I’m an active web and tool developer (code optimization, digital defense), a contributor to web standards (like HTML, CSS, WCAG), and a book author (O’Reilly, Frontend Dogma). Stay in touch.