html-minifier-next 4.16.3 → 4.17.0

package/README.md

@@ -2,13 +2,13 @@
 
 [![npm version](https://img.shields.io/npm/v/html-minifier-next.svg)](https://www.npmjs.com/package/html-minifier-next) [![Build status](https://github.com/j9t/html-minifier-next/workflows/Tests/badge.svg)](https://github.com/j9t/html-minifier-next/actions) [![Socket](https://badge.socket.dev/npm/package/html-minifier-next)](https://socket.dev/npm/package/html-minifier-next)
 
-HTML Minifier Next (HMN) is a **super-configurable, well-tested, JavaScript-based HTML minifier**.
+HTML Minifier Next (HMN) is a **super-configurable, well-tested, JavaScript-based HTML minifier** that can also handle in-document CSS, JavaScript, and SVG minification.
 
-The project was based on [HTML Minifier Terser](https://github.com/terser/html-minifier-terser), which in turn had been based on [Juriy “kangax” Zaytsev’s HTML Minifier](https://github.com/kangax/html-minifier). HMN offers additional features, but is backwards-compatible with both. The project was set up because as of 2025, both HTML Minifier Terser and HTML Minifier had been unmaintained for a few years. As the project seems maintainable [to me, [Jens](https://meiert.com/), an HTML optimizer]—even more so with community support—, it’s being [updated, extended, and documented](https://github.com/j9t/html-minifier-next/blob/main/CHANGELOG.md) further in this place.
+The project was based on [HTML Minifier Terser (HMT)](https://github.com/terser/html-minifier-terser), which in turn had been based on [Juriy “kangax” Zaytsev’s HTML Minifier (HM)](https://github.com/kangax/html-minifier); as of 2025, both HTML Minifier Terser and HTML Minifier had been unmaintained for several years. HMN offers additional features and has been optimized for speed. While an independent project, it is still backwards-compatible with HMT and HM.
 
 ## Installation
 
-From npm for use as a command line app:
+From npm for use as a command-line app:
 
 ```shell
 npm i -g html-minifier-next
@@ -39,15 +39,14 @@ Use `html-minifier-next --help` to check all available options:
 | `--output-dir <dir>` | Specify an output directory | `--output-dir=dist` |
 | `--file-ext <extensions>` | Specify file extension(s) to process (comma-separated, overrides config file setting) | `--file-ext=html`, `--file-ext=html,htm,php`, `--file-ext="html, htm, php"` |
 | `-o <file>`, `--output <file>` | Specify output file (reads from file arguments or STDIN) | File to file: `html-minifier-next input.html -o output.html`<br>Pipe to file: `cat input.html \| html-minifier-next -o output.html`<br>File to STDOUT: `html-minifier-next input.html` |
-| `-c <file>`, `--config-file <file>` | Use a configuration file | `--config-file=html-minifier.json` |
 | `--preset <name>` | Use a preset configuration (conservative or comprehensive) | `--preset=conservative` |
+| `-c <file>`, `--config-file <file>` | Use a configuration file | `--config-file=html-minifier.json` |
 | `-v`, `--verbose` | Show detailed processing information (active options, file statistics) | `html-minifier-next --input-dir=src --output-dir=dist --verbose --collapse-whitespace` |
 | `-d`, `--dry` | Dry run: Process and report statistics without writing output | `html-minifier-next input.html --dry --collapse-whitespace` |
-| `-V`, `--version` | Output the version number | `html-minifier-next --version` |
 
 ### Configuration file
 
-You can also use a configuration file to specify options. The file can be either JSON format or a JavaScript module that exports the configuration object:
+You can use a configuration file to specify options. The file can be either JSON format or a JavaScript module that exports the configuration object:
 
 **JSON configuration example:**
 
@@ -71,16 +70,6 @@ module.exports = {
 };
 ```
 
-**Using a configuration file:**
-
-```shell
-# Specify config file
-html-minifier-next --config-file=html-minifier.json --input-dir=src --output-dir=dist
-
-# CLI arguments override config file settings
-html-minifier-next --config-file=html-minifier.json --file-ext=xml --input-dir=src --output-dir=dist
-```
-
 ### Node.js
 
 ESM with Node.js ≥16.14:
@@ -88,35 +77,32 @@ ESM with Node.js ≥16.14:
 ```js
 import { minify } from 'html-minifier-next';
 
-const result = await minify('<p title="blah" id="moo">foo</p>', {
+const result = await minify('<p title="example" id="moo">foo</p>', {
   removeAttributeQuotes: true,
+  removeOptionalTags: true
 });
-console.log(result); // “<p title=blah id=moo>foo</p>”
+console.log(result); // “<p title=example id=moo>foo”
 ```
 
 CommonJS:
 
 ```js
-const { minify } = require('html-minifier-next');
+const { minify, getPreset } = require('html-minifier-next');
 
 (async () => {
-  const result = await minify('<p title="blah" id="moo">foo</p>', {
-    removeAttributeQuotes: true,
-  });
-  console.log(result);
+  const result = await minify('<p title="example" id="moo">foo</p>', getPreset('comprehensive'));
+  console.log(result); // “<p id=moo title=example>foo”
 })();
 ```
 
-See [the original blog post](https://perfectionkills.com/experimenting-with-html-minifier) for details of [how it works](https://perfectionkills.com/experimenting-with-html-minifier#how_it_works), [description of each option](https://perfectionkills.com/experimenting-with-html-minifier#options), [testing results](https://perfectionkills.com/experimenting-with-html-minifier#field_testing), and [conclusions](https://perfectionkills.com/experimenting-with-html-minifier#cost_and_benefits).
-
-For lint-like capabilities, take a look at [HTMLLint](https://github.com/kangax/html-lint).
+See [the original blog post](https://perfectionkills.com/experimenting-with-html-minifier/) for details of [how it works](https://perfectionkills.com/experimenting-with-html-minifier/#how_it_works), [descriptions of most options](https://perfectionkills.com/experimenting-with-html-minifier/#options), [testing results](https://perfectionkills.com/experimenting-with-html-minifier/#field_testing), and [conclusions](https://perfectionkills.com/experimenting-with-html-minifier/#cost_and_benefits).
 
 ## Presets
 
 HTML Minifier Next provides presets for common use cases. Presets are pre-configured option sets that can be used as a starting point:
 
 * `conservative`: Safe minification suitable for most projects. Includes whitespace collapsing, comment removal, and doctype normalization.
-* `comprehensive`: Aggressive minification for maximum file size reduction. Includes relevant conservative options plus attribute quote removal, optional tag removal, and more.
+* `comprehensive`: More aggressive minification for better file size reduction. Includes relevant conservative options plus attribute quote removal, optional tag removal, and more.
 
 To review the specific options set, [presets.js](https://github.com/j9t/html-minifier-next/blob/main/src/presets.js) lists them in an accessible manner.
 
@@ -146,16 +132,16 @@ Options can be used in config files (camelCase) or via CLI flags (kebab-case wit
 | --- | --- | --- |
 | `caseSensitive`<br>`--case-sensitive` | Treat attributes in case-sensitive manner (useful for custom HTML elements) | `false` |
 | `collapseAttributeWhitespace`<br>`--collapse-attribute-whitespace` | Trim and collapse whitespace characters within attribute values | `false` |
-| `collapseBooleanAttributes`<br>`--collapse-boolean-attributes` | [Omit attribute values from boolean attributes](https://perfectionkills.com/experimenting-with-html-minifier#collapse_boolean_attributes) | `false` |
-| `collapseInlineTagWhitespace`<br>`--collapse-inline-tag-whitespace` | Don’t leave any spaces between `display: inline;` elements when collapsing—use with `collapseWhitespace: true` | `false` |
-| `collapseWhitespace`<br>`--collapse-whitespace` | [Collapse whitespace that contributes to text nodes in a document tree](https://perfectionkills.com/experimenting-with-html-minifier#collapse_whitespace) | `false` |
+| `collapseBooleanAttributes`<br>`--collapse-boolean-attributes` | [Omit attribute values from boolean attributes](https://perfectionkills.com/experimenting-with-html-minifier/#collapse_boolean_attributes) | `false` |
+| `collapseInlineTagWhitespace`<br>`--collapse-inline-tag-whitespace` | Collapse whitespace more aggressively between inline elements—use with `collapseWhitespace: true` | `false` |
+| `collapseWhitespace`<br>`--collapse-whitespace` | [Collapse whitespace that contributes to text nodes in a document tree](https://perfectionkills.com/experimenting-with-html-minifier/#collapse_whitespace) | `false` |
 | `conservativeCollapse`<br>`--conservative-collapse` | Always collapse to one space (never remove it entirely)—use with `collapseWhitespace: true` | `false` |
 | `continueOnMinifyError`<br>`--no-continue-on-minify-error` | Continue on minification errors; when `false`, minification errors throw and abort processing | `true` |
 | `continueOnParseError`<br>`--continue-on-parse-error` | [Handle parse errors](https://html.spec.whatwg.org/multipage/parsing.html#parse-errors) instead of aborting | `false` |
-| `customAttrAssign`<br>`--custom-attr-assign` | Arrays of regexes that allow to support custom attribute assign expressions (e.g., `<div flex?="{{mode != cover}}"></div>`) | `[]` |
-| `customAttrCollapse`<br>`--custom-attr-collapse` | Regex that specifies custom attribute to strip newlines from (e.g., `/ng-class/`) | |
-| `customAttrSurround`<br>`--custom-attr-surround` | Arrays of regexes that allow to support custom attribute surround expressions (e.g., `<input {{#if value}}checked="checked"{{/if}}>`) | `[]` |
-| `customEventAttributes`<br>`--custom-event-attributes` | Arrays of regexes that allow to support custom event attributes for `minifyJS` (e.g., `ng-click`) | `[ /^on[a-z]{3,}$/ ]` |
+| `customAttrAssign`<br>`--custom-attr-assign` | Array of regexes that allow to support custom attribute assign expressions (e.g., `<div flex?="{{mode != cover}}"></div>`) | `[]` |
+| `customAttrCollapse`<br>`--custom-attr-collapse` | Regex that specifies custom attribute to strip newlines from (e.g., `/ng-class/`) | `undefined` |
+| `customAttrSurround`<br>`--custom-attr-surround` | Array of regexes that allow to support custom attribute surround expressions (e.g., `<input {{#if value}}checked="checked"{{/if}}>`) | `[]` |
+| `customEventAttributes`<br>`--custom-event-attributes` | Array of regexes that allow to support custom event attributes for `minifyJS` (e.g., `ng-click`) | `[ /^on[a-z]{3,}$/ ]` |
 | `customFragmentQuantifierLimit`<br>`--custom-fragment-quantifier-limit` | Set maximum quantifier limit for custom fragments to prevent ReDoS attacks | `200` |
 | `decodeEntities`<br>`--decode-entities` | Use direct Unicode characters whenever possible | `false` |
 | `html5`<br>`--no-html5` | Parse input according to the HTML specification; when `false`, enforces legacy inline/block nesting rules that may restructure modern HTML | `true` |
@@ -165,8 +151,8 @@ Options can be used in config files (camelCase) or via CLI flags (kebab-case wit
 | `inlineCustomElements`<br>`--inline-custom-elements` | Array of names of custom elements which are inline | `[]` |
 | `keepClosingSlash`<br>`--keep-closing-slash` | Keep the trailing slash on void elements | `false` |
 | `maxInputLength`<br>`--max-input-length` | Maximum input length to prevent ReDoS attacks (disabled by default) | `undefined` |
-| `maxLineLength`<br>`--max-line-length` | Specify a maximum line length; compressed output will be split by newlines at valid HTML split-points | |
-| `minifyCSS`<br>`--minify-css` | Minify CSS in `style` elements and `style` attributes (uses [Lightning CSS](https://lightningcss.dev/)) | `false` (could be `true`, `Object`, `Function(text, type)`) |
+| `maxLineLength`<br>`--max-line-length` | Specify a maximum line length; compressed output will be split by newlines at valid HTML split-points | `undefined` |
+| `minifyCSS`<br>`--minify-css` | Minify CSS in `style` elements and attributes (uses [Lightning CSS](https://lightningcss.dev/)) | `false` (could be `true`, `Object`, `Function(text, type)`) |
 | `minifyJS`<br>`--minify-js` | Minify JavaScript in `script` elements and event attributes (uses [Terser](https://github.com/terser/terser) or [SWC](https://swc.rs/)) | `false` (could be `true`, `Object`, `Function(text, inline)`) |
 | `minifySVG`<br>`--minify-svg` | Minify SVG elements and attributes (numeric precision, default attributes, colors) | `false` (could be `true`, `Object`) |
 | `minifyURLs`<br>`--minify-urls` | Minify URLs in various attributes (uses [relateurl](https://github.com/stevenvachon/relateurl)) | `false` (could be `String`, `Object`, `Function(text)`, `async Function(text)`) |
@@ -177,20 +163,20 @@ Options can be used in config files (camelCase) or via CLI flags (kebab-case wit
 | `processConditionalComments`<br>`--process-conditional-comments` | Process contents of conditional comments through minifier | `false` |
 | `processScripts`<br>`--process-scripts` | Array of strings corresponding to types of `script` elements to process through minifier (e.g., `text/ng-template`, `text/x-handlebars-template`, etc.) | `[]` |
 | `quoteCharacter`<br>`--quote-character` | Type of quote to use for attribute values (`'` or `"`) | Auto-detected (uses the quote requiring less escaping; defaults to `"` when equal) |
-| `removeAttributeQuotes`<br>`--remove-attribute-quotes` | [Remove quotes around attributes when possible](https://perfectionkills.com/experimenting-with-html-minifier#remove_attribute_quotes) | `false` |
-| `removeComments`<br>`--remove-comments` | [Strip HTML comments](https://perfectionkills.com/experimenting-with-html-minifier#remove_comments) | `false` |
-| `removeEmptyAttributes`<br>`--remove-empty-attributes` | [Remove all attributes with whitespace-only values](https://perfectionkills.com/experimenting-with-html-minifier#remove_empty_or_blank_attributes) | `false` (could be `true`, `Function(attrName, tag)`) |
-| `removeEmptyElements`<br>`--remove-empty-elements` | [Remove all elements with empty contents](https://perfectionkills.com/experimenting-with-html-minifier#remove_empty_elements) | `false` |
+| `removeAttributeQuotes`<br>`--remove-attribute-quotes` | [Remove quotes around attributes when possible](https://perfectionkills.com/experimenting-with-html-minifier/#remove_attribute_quotes) | `false` |
+| `removeComments`<br>`--remove-comments` | [Strip HTML comments](https://perfectionkills.com/experimenting-with-html-minifier/#remove_comments) | `false` |
+| `removeEmptyAttributes`<br>`--remove-empty-attributes` | [Remove all attributes with whitespace-only values](https://perfectionkills.com/experimenting-with-html-minifier/#remove_empty_or_blank_attributes) | `false` (could be `true`, `Function(attrName, tag)`) |
+| `removeEmptyElements`<br>`--remove-empty-elements` | [Remove all elements with empty contents](https://perfectionkills.com/experimenting-with-html-minifier/#remove_empty_elements) | `false` |
 | `removeEmptyElementsExcept`<br>`--remove-empty-elements-except` | Array of elements to preserve when `removeEmptyElements` is enabled; accepts simple tag names (e.g., `["td"]`) or HTML-like markup with attributes (e.g., `["<span aria-hidden='true'>"]`); supports double quotes, single quotes, and unquoted attribute values | `[]` |
-| `removeOptionalTags`<br>`--remove-optional-tags` | [Remove optional tags](https://perfectionkills.com/experimenting-with-html-minifier#remove_optional_tags) | `false` |
+| `removeOptionalTags`<br>`--remove-optional-tags` | [Remove optional tags](https://perfectionkills.com/experimenting-with-html-minifier/#remove_optional_tags) | `false` |
 | `removeRedundantAttributes`<br>`--remove-redundant-attributes` | [Remove attributes when value matches default](https://meiert.com/blog/optional-html/#toc-attribute-values) | `false` |
 | `removeScriptTypeAttributes`<br>`--remove-script-type-attributes` | Remove `type="text/javascript"` from `script` elements; other `type` attribute values are left intact | `false` |
 | `removeStyleLinkTypeAttributes`<br>`--remove-style-link-type-attributes` | Remove `type="text/css"` from `style` and `link` elements; other `type` attribute values are left intact | `false` |
 | `removeTagWhitespace`<br>`--remove-tag-whitespace` | Remove space between attributes whenever possible; **note that this will result in invalid HTML** | `false` |
 | `sortAttributes`<br>`--sort-attributes` | [Sort attributes by frequency](#sorting-attributes-and-style-classes) | `false` |
 | `sortClassName`<br>`--sort-class-name` | [Sort style classes by frequency](#sorting-attributes-and-style-classes) | `false` |
-| `trimCustomFragments`<br>`--trim-custom-fragments` | Trim whitespace around `ignoreCustomFragments` | `false` |
-| `useShortDoctype`<br>`--use-short-doctype` | [Replaces the doctype with the short (HTML) doctype](https://perfectionkills.com/experimenting-with-html-minifier#use_short_doctype) | `false` |
+| `trimCustomFragments`<br>`--trim-custom-fragments` | Trim whitespace around custom fragments (`ignoreCustomFragments`) | `false` |
+| `useShortDoctype`<br>`--use-short-doctype` | [Replaces the doctype with the short HTML doctype](https://perfectionkills.com/experimenting-with-html-minifier/#use_short_doctype) | `false` |
 
 ### Sorting attributes and style classes
 
@@ -198,7 +184,7 @@ Minifier options like `sortAttributes` and `sortClassName` won’t impact the pl
 
 ### CSS minification
 
-When `minifyCSS` is set to `true`, HTML Minifier Next uses [Lightning CSS](https://lightningcss.dev/) to minify CSS in `<style>` elements and `style` attributes. Lightning CSS provides excellent minification by default.
+When `minifyCSS` is set to `true`, HTML Minifier Next uses [Lightning CSS](https://lightningcss.dev/) to minify CSS in `style` elements and attributes. Lightning CSS provides excellent minification by default.
 
 You can pass Lightning CSS configuration options by providing an object:
 
@@ -357,39 +343,39 @@ How does HTML Minifier Next compare to other minifiers? (All minification with t
 <!-- Auto-generated benchmarks, don’t edit -->
 | Site | Original Size (KB) | [HTML Minifier Next](https://github.com/j9t/html-minifier-next) ([config](https://github.com/j9t/html-minifier-next/blob/main/benchmarks/html-minifier.json))<br>[![npm last update](https://img.shields.io/npm/last-update/html-minifier-next)](https://socket.dev/npm/package/html-minifier-next) | [htmlnano](https://github.com/posthtml/htmlnano)<br>[![npm last update](https://img.shields.io/npm/last-update/htmlnano)](https://socket.dev/npm/package/htmlnano) | [@swc/html](https://github.com/swc-project/swc)<br>[![npm last update](https://img.shields.io/npm/last-update/@swc/html)](https://socket.dev/npm/package/@swc/html) | [minify-html](https://github.com/wilsonzlin/minify-html)<br>[![npm last update](https://img.shields.io/npm/last-update/@minify-html/node)](https://socket.dev/npm/package/@minify-html/node) | [minimize](https://github.com/Swaagie/minimize)<br>[![npm last update](https://img.shields.io/npm/last-update/minimize)](https://socket.dev/npm/package/minimize) | [html­com­pressor.­com](https://htmlcompressor.com/) |
 | --- | --- | --- | --- | --- | --- | --- | --- |
-| [A List Apart](https://alistapart.com/) | 59 | **50** | 51 | 52 | 51 | 54 | 52 |
-| [Apple](https://www.apple.com/) | 211 | **176** | 187 | 189 | 190 | 191 | 192 |
-| [BBC](https://www.bbc.co.uk/) | 686 | **624** | 643 | 644 | 645 | 680 | n/a |
-| [CERN](https://home.cern/) | 152 | **83** | 91 | 91 | 91 | 93 | 96 |
-| [CSS-Tricks](https://css-tricks.com/) | 162 | **119** | 127 | 143 | 143 | 148 | 144 |
+| [A List Apart](https://alistapart.com/) | 59 | **49** | 51 | 52 | 51 | 54 | 52 |
+| [Apple](https://www.apple.com/) | 259 | **201** | 230 | 234 | 234 | 236 | 237 |
+| [BBC](https://www.bbc.co.uk/) | 647 | **586** | 608 | 608 | 609 | 642 | n/a |
+| [CERN](https://home.cern/) | 151 | **83** | 91 | 91 | 91 | 93 | 96 |
+| [CSS-Tricks](https://css-tricks.com/) | 161 | **119** | 127 | 142 | 142 | 147 | 144 |
 | [ECMAScript](https://tc39.es/ecma262/) | 7250 | **6401** | 6573 | 6455 | 6578 | 6626 | n/a |
 | [EDRi](https://edri.org/) | 80 | **59** | 70 | 70 | 71 | 75 | 73 |
-| [EFF](https://www.eff.org/) | 54 | **45** | 49 | 47 | 48 | 49 | 49 |
+| [EFF](https://www.eff.org/) | 55 | **46** | 49 | 48 | 48 | 50 | 50 |
 | [European Alternatives](https://european-alternatives.eu/) | 48 | **30** | 32 | 32 | 32 | 32 | 32 |
-| [FAZ](https://www.faz.net/aktuell/) | 1587 | 1476 | **1421** | 1511 | 1522 | 1533 | n/a |
+| [FAZ](https://www.faz.net/aktuell/) | 1579 | 1468 | **1416** | 1503 | 1515 | 1526 | n/a |
 | [French Tech](https://lafrenchtech.gouv.fr/) | 153 | **122** | 126 | 126 | 126 | 132 | 127 |
-| [Frontend Dogma](https://frontenddogma.com/) | 225 | **217** | 238 | 223 | 225 | 244 | 225 |
+| [Frontend Dogma](https://frontenddogma.com/) | 227 | **219** | 240 | 225 | 227 | 245 | 226 |
 | [Google](https://www.google.com/) | 18 | **16** | 17 | 17 | 17 | 18 | 18 |
-| [Ground News](https://ground.news/) | 2291 | **2005** | 2106 | 2136 | 2139 | 2278 | n/a |
+| [Ground News](https://ground.news/) | 2626 | **2321** | 2417 | 2444 | 2446 | 2613 | n/a |
 | [HTML Living Standard](https://html.spec.whatwg.org/multipage/) | 149 | 148 | 153 | **147** | 149 | 155 | 149 |
-| [Igalia](https://www.igalia.com/) | 50 | **33** | 36 | 36 | 36 | 37 | 37 |
-| [Leanpub](https://leanpub.com/) | 235 | **205** | 220 | 219 | 220 | 230 | 232 |
+| [Igalia](https://www.igalia.com/) | 48 | **33** | 35 | 35 | 35 | 36 | 36 |
+| [Leanpub](https://leanpub.com/) | 245 | **214** | 228 | 228 | 229 | 241 | 242 |
 | [Mastodon](https://mastodon.social/explore) | 37 | **28** | 32 | 35 | 35 | 36 | 36 |
 | [MDN](https://developer.mozilla.org/en-US/) | 109 | **62** | 64 | 65 | 65 | 68 | 68 |
-| [Middle East Eye](https://www.middleeasteye.net/) | 223 | **197** | 203 | 201 | 201 | 202 | 203 |
-| [Mistral AI](https://mistral.ai/) | 361 | **319** | 324 | 326 | 327 | 357 | n/a |
-| [Mozilla](https://www.mozilla.org/) | 45 | **31** | 34 | 34 | 34 | 35 | 35 |
-| [Nielsen Norman Group](https://www.nngroup.com/) | 86 | 68 | **55** | 74 | 75 | 77 | 76 |
-| [SitePoint](https://www.sitepoint.com/) | 482 | **351** | 422 | 456 | 460 | 478 | n/a |
-| [Startup-Verband](https://startupverband.de/) | 42 | **29** | 30 | 30 | 30 | 31 | 30 |
-| [TetraLogical](https://tetralogical.com/) | 44 | 38 | **35** | 38 | 39 | 39 | 39 |
-| [TPGi](https://www.tpgi.com/) | 174 | **158** | 159 | 163 | 165 | 171 | 171 |
-| [United Nations](https://www.un.org/en/) | 152 | **112** | 121 | 125 | 125 | 130 | 123 |
-| [Vivaldi](https://vivaldi.com/) | 92 | **74** | n/a | 79 | 81 | 83 | 81 |
-| [W3C](https://www.w3.org/) | 51 | **36** | 39 | 38 | 38 | 41 | 39 |
-| **Average processing time** |  | 100 ms (30/30) | 157 ms (29/30) | 52 ms (30/30) | **14 ms (30/30)** | 278 ms (30/30) | 1385 ms (24/30) |
-
-(Last updated: Dec 27, 2025)
+| [Middle East Eye](https://www.middleeasteye.net/) | 222 | **196** | 202 | 200 | 200 | 202 | 202 |
+| [Mistral AI](https://mistral.ai/) | 356 | **313** | 318 | 322 | 323 | 352 | n/a |
+| [Mozilla](https://www.mozilla.org/) | 45 | **31** | 35 | 34 | 34 | 35 | 35 |
+| [Nielsen Norman Group](https://www.nngroup.com/) | 93 | 70 | **57** | 75 | 77 | 78 | 77 |
+| [SitePoint](https://www.sitepoint.com/) | 478 | **347** | 419 | 452 | 457 | 475 | n/a |
+| [Startup-Verband](https://startupverband.de/) | 43 | **30** | 31 | **30** | 31 | 31 | 31 |
+| [TetraLogical](https://tetralogical.com/) | 44 | 39 | **36** | 38 | 39 | 39 | 39 |
+| [TPGi](https://www.tpgi.com/) | 175 | **159** | 160 | 164 | 166 | 172 | 172 |
+| [United Nations](https://www.un.org/en/) | 152 | **113** | 122 | 126 | 126 | 131 | 124 |
+| [Vivaldi](https://vivaldi.com/) | 93 | **74** | n/a | 79 | 81 | 84 | 82 |
+| [W3C](https://www.w3.org/) | 50 | **36** | 39 | 38 | 38 | 41 | 39 |
+| **Average processing time** |  | 97 ms (30/30) | 157 ms (29/30) | 51 ms (30/30) | **15 ms (30/30)** | 289 ms (30/30) | 1288 ms (24/30) |
+
+(Last updated: Jan 8, 2026)
 <!-- End auto-generated -->
 
 Notes: Minimize does not minify CSS and JS. [HTML Minifier Terser](https://github.com/terser/html-minifier-terser) is currently not included due to issues around whitespace collapsing and removal of code using modern CSS features, issues which appeared to distort the data.
@@ -404,7 +390,7 @@ Notes: Minimize does not minify CSS and JS. [HTML Minifier Terser](https://githu
 html-minifier-next --collapse-whitespace --remove-comments --minify-js --input-dir=. --output-dir=example
 ```
 
-Another example, using npx:
+Example using npx:
 
 ```shell
 npx html-minifier-next --input-dir=test --file-ext html --preset comprehensive --output-dir example
@@ -552,6 +538,44 @@ ignoreCustomFragments: [/\{\{[\s\S]{0,500}?\}\}/]
 
 **Important:** When using custom `ignoreCustomFragments`, the minifier automatically applies bounded quantifiers to prevent ReDoS attacks, but you can also write safer patterns yourself using explicit bounds.
 
+##### Escaping patterns in different contexts
+
+The escaping requirements for `ignoreCustomFragments` patterns differ depending on how you’re using HMN:
+
+**Config file (JSON):**
+
+```json
+{
+  "ignoreCustomFragments": ["\\{%[\\s\\S]{0,1000}?%\\}", "\\{\\{[\\s\\S]{0,500}?\\}\\}"]
+}
+```
+
+**Programmatic (JavaScript/Node.js):**
+
+```javascript
+ignoreCustomFragments: [/\{%[\s\S]{0,1000}?%\}/, /\{\{[\s\S]{0,500}?\}\}/]
+```
+
+**CLI (via config file—recommended):**
+
+```shell
+html-minifier-next --config-file=config.json input.html
+```
+
+**CLI (inline—not recommended due to complex escaping):**
+
+```shell
+html-minifier-next --ignore-custom-fragments '[\\\"\\\\{%[\\\\s\\\\S]{0,1000}?%\\\\}\\\"]' input.html
+```
+
+For CLI usage, using a config file is strongly recommended to avoid complex shell and JSON escaping.
+
+**[Web demo:](https://j9t.github.io/html-minifier-next/)**
+
+```
+\{%[\s\S]{0,1000}?%\} \{\{[\s\S]{0,500}?\}\}
+```
+
 ## Running HTML Minifier Next locally
 
 ### Local server
@@ -572,6 +596,22 @@ npm run benchmarks
 
 (In case of dependency conflicts, run `npm i` with the `--legacy-peer-deps` flag.)
 
+### Regression tests
+
+```shell
+cd benchmarks;
+npm i;
+npm run backtest
+```
+
+The backtest tool tracks minification performance across Git history. Results are saved in `benchmarks/backtest/` as CSV and JSON files.
+
+Parameters:
+
+* No argument: Tests last 50 commits (default)
+* `COUNT`: Tests last `COUNT` commits (e.g., `npm run backtest 100`)
+* `COUNT/STEP`: Tests last `COUNT` commits, sampling every `STEP`th commit (e.g., `npm run backtest 500/10` tests 50 commits)
+
 ## Acknowledgements
 
 With many thanks to all the previous authors of HTML Minifier, especially [Juriy “kangax” Zaytsev](https://github.com/kangax), and to everyone who helped make this new edition better, particularly [Daniel Ruf](https://github.com/DanielRuf) and [Jonas Geiler](https://github.com/jonasgeiler).

package/cli.js

@@ -4,7 +4,11 @@
  *
  * The MIT License (MIT)
  *
- *  Copyright (c) 2014-2016 Zoltan Frombach
+ *  Copyright 2014–2016 Zoltan Frombach
+ *
+ *  Copyright Juriy “kangax” Zaytsev
+ *
+ *  Copyright 2025 Jens Oliver Meiert
  *
  *  Permission is hereby granted, free of charge, to any person obtaining a copy of
  *  this software and associated documentation files (the "Software"), to deal in
@@ -33,7 +37,6 @@ import { createRequire } from 'module';
 import { camelCase, paramCase } from 'change-case';
 import { Command } from 'commander';
 // Lazy-load HMN to reduce CLI cold-start overhead
-// import { minify } from './src/htmlminifier.js';
 import { getPreset, getPresetNames } from './src/presets.js';
 
 const require = createRequire(import.meta.url);
@@ -57,7 +60,7 @@ process.stdout.on('error', (err) => {
 });
 
 /**
- * JSON does not support regexes, so, e.g., JSON.parse() will not create
+ * JSON does not support regexes, so, e.g., `JSON.parse()` will not create
  * a RegExp from the JSON value `[ "/matchString/" ]`, which is
  * technically just an array containing a string that begins and end with
  * a forward slash. To get a RegExp from a JSON string, it must be
@@ -121,53 +124,53 @@ const mainOptions = {
   caseSensitive: 'Treat attributes in case-sensitive manner (useful for custom HTML elements)',
   collapseAttributeWhitespace: 'Trim and collapse whitespace characters within attribute values',
   collapseBooleanAttributes: 'Omit attribute values from boolean attributes',
-  collapseInlineTagWhitespace: 'Don’t leave any spaces between “display: inline;” elements when collapsing—use with “--collapse-whitespace”',
+  collapseInlineTagWhitespace: 'Collapse whitespace more aggressively between inline elements—use with `--collapse-whitespace`',
   collapseWhitespace: 'Collapse whitespace that contributes to text nodes in a document tree',
-  conservativeCollapse: 'Always collapse to one space (never remove it entirely)—use with “--collapse-whitespace”',
+  conservativeCollapse: 'Always collapse to one space (never remove it entirely)—use with `--collapse-whitespace`',
   continueOnMinifyError: 'Abort on minification errors',
   continueOnParseError: 'Handle parse errors instead of aborting',
-  customAttrAssign: ['Arrays of regexes that allow to support custom attribute assign expressions (e.g., “<div flex?="{{mode != cover}}"></div>”)', parseJSONRegExpArray],
+  customAttrAssign: ['Array of regexes that allow to support custom attribute assign expressions (e.g., `<div flex?="{{mode != cover}}"></div>`)', parseJSONRegExpArray],
   customAttrCollapse: ['Regex that specifies custom attribute to strip newlines from (e.g., /ng-class/)', parseRegExp],
-  customAttrSurround: ['Arrays of regexes that allow to support custom attribute surround expressions (e.g., “<input {{#if value}}checked="checked"{{/if}}>”)', parseJSONRegExpArray],
-  customEventAttributes: ['Arrays of regexes that allow to support custom event attributes for minifyJS (e.g., “ng-click”)', parseJSONRegExpArray],
+  customAttrSurround: ['Array of regexes that allow to support custom attribute surround expressions (e.g., `<input {{#if value}}checked="checked"{{/if}}>`)', parseJSONRegExpArray],
+  customEventAttributes: ['Array of regexes that allow to support custom event attributes for minifyJS (e.g., `ng-click`)', parseJSONRegExpArray],
   customFragmentQuantifierLimit: ['Set maximum quantifier limit for custom fragments to prevent ReDoS attacks (default: 200)', parseValidInt('customFragmentQuantifierLimit')],
   decodeEntities: 'Use direct Unicode characters whenever possible',
   html5: 'Don’t parse input according to the HTML specification (not recommended for modern HTML)',
   ignoreCustomComments: ['Array of regexes that allow to ignore certain comments, when matched', parseJSONRegExpArray],
-  ignoreCustomFragments: ['Array of regexes that allow to ignore certain fragments, when matched (e.g., “<?php … ?>”, “{{ … }}”)', parseJSONRegExpArray],
+  ignoreCustomFragments: ['Array of regexes that allow to ignore certain fragments, when matched (e.g., `<?php … ?>`, `{{ … }}`)', parseJSONRegExpArray],
   includeAutoGeneratedTags: 'Don’t insert elements generated by HTML parser',
   inlineCustomElements: ['Array of names of custom elements which are inline', parseJSONArray],
   keepClosingSlash: 'Keep the trailing slash on void elements',
   maxInputLength: ['Maximum input length to prevent ReDoS attacks', parseValidInt('maxInputLength')],
   maxLineLength: ['Specify a maximum line length; compressed output will be split by newlines at valid HTML split-points', parseValidInt('maxLineLength')],
-  minifyCSS: ['Minify CSS in "style" elements and "style" attributes (uses Lightning CSS)', parseJSON],
-  minifyJS: ['Minify JavaScript in "script" elements and event attributes (uses Terser or SWC; pass "{"engine": "swc"}" for SWC)', parseJSON],
+  minifyCSS: ['Minify CSS in `style` elements and attributes (uses Lightning CSS)', parseJSON],
+  minifyJS: ['Minify JavaScript in `script` elements and event attributes (uses Terser or SWC; pass `{"engine": "swc"}` for SWC)', parseJSON],
   minifySVG: ['Minify SVG elements and attributes (numeric precision, default attributes, colors)', parseJSON],
   minifyURLs: ['Minify URLs in various attributes (uses relateurl)', parseJSON],
   noNewlinesBeforeTagClose: 'Never add a newline before a tag that closes an element',
   partialMarkup: 'Treat input as a partial HTML fragment, preserving stray end tags and unclosed tags',
-  preserveLineBreaks: 'Always collapse to one line break (never remove it entirely) when whitespace between tags includes a line break—use with “--collapse-whitespace”',
+  preserveLineBreaks: 'Always collapse to one line break (never remove it entirely) when whitespace between tags includes a line break—use with `--collapse-whitespace`',
   preventAttributesEscaping: 'Prevents the escaping of the values of attributes',
   processConditionalComments: 'Process contents of conditional comments through minifier',
-  processScripts: ['Array of strings corresponding to types of “script” elements to process through minifier (e.g., “text/ng-template”, “text/x-handlebars-template”, etc.)', parseJSONArray],
+  processScripts: ['Array of strings corresponding to types of `script` elements to process through minifier (e.g., `text/ng-template`, `text/x-handlebars-template`, etc.)', parseJSONArray],
   quoteCharacter: ['Type of quote to use for attribute values (“\'” or “"”)', parseString],
   removeAttributeQuotes: 'Remove quotes around attributes when possible',
   removeComments: 'Strip HTML comments',
   removeEmptyAttributes: 'Remove all attributes with whitespace-only values',
   removeEmptyElements: 'Remove all elements with empty contents',
-  removeEmptyElementsExcept: ['Array of elements to preserve when “--remove-empty-elements” is enabled (e.g., “td”, “["td", "<span aria-hidden=\'true\'>"]”)', parseJSONArray],
+  removeEmptyElementsExcept: ['Array of elements to preserve when `--remove-empty-elements` is enabled (e.g., `td`, `["td", "<span aria-hidden=\'true\'>"]`)', parseJSONArray],
   removeOptionalTags: 'Remove unrequired tags',
   removeRedundantAttributes: 'Remove attributes when value matches default',
-  removeScriptTypeAttributes: 'Remove “type="text/javascript"” from “script” elements; other “type” attribute values are left intact',
-  removeStyleLinkTypeAttributes: 'Remove “type="text/css"” from “style” and “link” elements; other “type” attribute values are left intact',
+  removeScriptTypeAttributes: 'Remove `type="text/javascript"` from `script` elements; other `type` attribute values are left intact',
+  removeStyleLinkTypeAttributes: 'Remove `type="text/css"` from `style` and `link` elements; other `type` attribute values are left intact',
   removeTagWhitespace: 'Remove space between attributes whenever possible; note that this will result in invalid HTML',
   sortAttributes: 'Sort attributes by frequency',
   sortClassName: 'Sort style classes by frequency',
-  trimCustomFragments: 'Trim whitespace around “ignoreCustomFragments”',
-  useShortDoctype: 'Replaces the doctype with the short (HTML) doctype'
+  trimCustomFragments: 'Trim whitespace around custom fragments (`--ignore-custom-fragments`)',
+  useShortDoctype: 'Replaces the doctype with the short HTML doctype'
 };
 
-// Configure command line flags
+// Configure command-line flags
 const mainOptionKeys = Object.keys(mainOptions);
 mainOptionKeys.forEach(function (key) {
   const option = mainOptions[key];
@@ -183,7 +186,7 @@ mainOptionKeys.forEach(function (key) {
 });
 program.option('-o --output <file>', 'Specify output file (reads from file arguments or STDIN; outputs to STDOUT if not specified)');
 program.option('-v --verbose', 'Show detailed processing information');
-program.option('-d --dry', 'Dry run: process and report statistics without writing output');
+program.option('-d --dry', 'Dry run: Process and report statistics without writing output');
 
 // Lazy import wrapper for HMN
 let minifyFnPromise;
@@ -219,7 +222,7 @@ async function loadConfigFromPath(configPath) {
     // Try CJS require
     try {
       const result = require(abs);
-      // Handle ESM interop: if `require()` loads an ESM file, it may return `{__esModule: true, default: …}`
+      // Handle ESM interop: If `require()` loads an ESM file, it may return `{__esModule: true, default: …}`
       return (result && result.__esModule && result.default) ? result.default : result;
     } catch (cjsErr) {
       // Try ESM import
@@ -252,7 +255,7 @@ function normalizeConfig(config) {
     }
   });
 
-  // Handle fileExt in config file
+  // Handle `fileExt` in config file
   if ('fileExt' in normalized) {
     // Support both string (`html,htm`) and array (`["html", "htm"]`) formats
     if (Array.isArray(normalized.fileExt)) {
@@ -445,8 +448,7 @@ program.option('--file-ext <extensions>', 'Specify file extension(s) to process
 
     return ignorePatterns.some(pattern => {
       // Support both exact directory names and relative paths
-      return dirName === pattern || relativePath === pattern ||
-             relativePath.startsWith(pattern + '/');
+      return dirName === pattern || relativePath === pattern || relativePath.startsWith(pattern + '/');
     });
   }
 
@@ -697,7 +699,7 @@ program.option('--file-ext <extensions>', 'Specify file extension(s) to process
       }
 
       // Resolve base directory for consistent path comparisons
-      const inputDirResolved = await fs.promises.realpath(inputDir).catch(() => inputDir);
+      const inputDirResolved = inputReal || inputDir;
 
       if (showProgress) {
         // Start with indeterminate progress, count in background