# html-minifier-next

> Highly effective, super-configurable, well-tested web page minifier (enhanced successor to HTML Minifier)

Latest version **8.4.5** (published 2026-09-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install html-minifier-next
pnpm add html-minifier-next
yarn add html-minifier-next
bun add html-minifier-next
```

Provides the commands `hmn`, `html-minifier-next`.

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 8.4.5 |
| Published | 2026-09-14 |
| First published | 2025-05-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/html-minifier-next) |
| Module format | ESM |
| Node | >=22.13 |
| Dependencies | 5 |
| Unpacked size | 516.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 154 |
| Author | Jens Oliver Meiert |
| Maintainers | j9t |
| Keywords | cli, compress, compressor, css, html, htmlmin, javascript, js, min, minification, minifier, minify, optimize, optimizer, pack, packer, svg, svgo, swc, terser, uglifier, uglify |

## Links

- npm: https://www.npmjs.com/package/html-minifier-next
- Repository: https://github.com/j9t/html-minifier-next
- Homepage: https://j9t.github.io/html-minifier-next/
- Issues: https://github.com/j9t/html-minifier-next/issues
- Funding: https://github.com/j9t/html-minifier-next?sponsor=1
- npm.io page: https://npm.io/package/html-minifier-next

## Dependencies (5)

- [svgo](https://npm.io/package/svgo.md) ^4.1.0
- [terser](https://npm.io/package/terser.md) ^5.51.2
- [entities](https://npm.io/package/entities.md) ^8.1.0
- [commander](https://npm.io/package/commander.md) ^15.0.0
- [lightningcss](https://npm.io/package/lightningcss.md) ^1.33.0

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 8.4.5 (latest) — 2026-09-14
- 8.4.4 — 2026-09-14
- 8.4.3 — 2026-09-14
- 8.4.2 — 2026-09-09
- 8.4.1 — 2026-09-08
- 8.4.0 — 2026-09-04
- 8.3.1 — 2026-08-30
- 8.3.0 — 2026-08-27
- 8.2.2 — 2026-08-26
- 8.2.1 — 2026-08-26
- 8.2.0 — 2026-08-26
- 8.1.2 — 2026-08-25
- 8.1.1 — 2026-08-24
- 8.1.0 — 2026-08-19
- 8.0.0 — 2026-08-19
- … 117 more at https://npm.io/package/html-minifier-next/versions

## README

# HTML Minifier Next

[![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) [![GitHub Sponsors](https://badgen.net/static/Support/Open%20Source/cyan)](https://github.com/sponsors/j9t)

Your web page optimization precision tool: HTML Minifier Next (HMN) is a **highly effective, super-configurable, well-tested HTML minifier**, written in JavaScript, that also handles in-document CSS, JavaScript, and SVG minification.

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). HMN is **the official successor to HTML Minifier**: It’s actively maintained, richer in features, easier to use, and significantly faster. Note that HMN is largely compatible with HM and HMT but isn’t fully drop-in—find [migration guidance in the changelog](https://github.com/j9t/html-minifier-next/blob/main/CHANGELOG.md).

## Installation

HTML Minifier Next is ESM-only and requires Node.js ≥22.13.

For use as a command-line app, use npx:

```shell
npx html-minifier-next --help
```

(For immediate, zero-config use in the current folder: `npx html-minifier-next --zero`)

For programmatic use, install as a development dependency:

```shell
npm i -D html-minifier-next
```

## General usage

### CLI

Use `npx html-minifier-next --help` to check all available options:

| Option | Description | Example |
| --- | --- | --- |
| `--zero`, `-z` | Minify all HTML files in the current folder and its subfolders in place (except node_modules), using comprehensive settings (standalone—flag is ignored when combined with other options) | `npx html-minifier-next --zero` |
| `--input-dir <dir>`, `-I <dir>` | Specify an input directory | `--input-dir=src` |
| `--ignore-dir <patterns>`, `-X <patterns>` | Exclude directories—relative to input directory—from processing (comma-separated, overrides config file setting) | `--ignore-dir=libs`, `--ignore-dir=libs,vendor,node_modules` |
| `--output-dir <dir>`, `-O <dir>` | Specify an output directory | `--output-dir=dist` |
| `--workers <n>`, `-w <n>` | Number of worker threads for multi-file runs; defaults to half the available cores (at most 6) for runs large enough to justify them | `--workers=4` |
| `--input <file>`, `-i <file>` | Specify input file (alternative to positional argument; pair with `--output` for file output) | `npx html-minifier-next -i input.html -o output.html` |
| `--output <file>`, `-o <file>` | Specify output file (reads from `--input` file argument or STDIN; outputs to STDOUT if not specified) | File to file: `npx html-minifier-next input.html -o output.html`<br>File to file (explicit): `npx html-minifier-next -i input.html -o output.html`<br>Pipe to file: `cat input.html \| npx html-minifier-next -o output.html`<br>File to STDOUT: `npx html-minifier-next input.html` |
| `--file-ext <extensions>`, `-f <extensions>` | Specify file extension(s) to process (comma-separated, overrides config file setting); defaults to `html,htm,shtml,shtm`; use `*` for all files | `--file-ext=html,php`, `--file-ext='*'` |
| `--preset <name>`, `-p <name>` | Use a preset configuration (conservative or comprehensive) | `--preset=conservative` |
| `--config-file <file>`, `-c <file>` | Use a configuration file (defaults to html-minifier-next.config.json in the working directory, if present) | `--config-file=path/to/config.json` |
| `--verbose`, `-v` | Show detailed processing information (active options, worker thread count, file statistics, and minifier warnings) | `npx html-minifier-next --input-dir=src --output-dir=dist --verbose --collapse-whitespace` |
| `--dry`, `-d` | Dry run: Process and report statistics without writing output | `npx html-minifier-next input.html --dry --collapse-whitespace` |

### Configuration file

You can use a configuration file to specify options. If an html-minifier-next.config.json file is present in the current working directory—only there; subfolders (including `--input-dir`) and parent folders are not searched—the CLI picks it up automatically, with a note on STDERR confirming this. An explicit `--config-file` takes precedence. (The standalone `--zero` mode is deliberately config-free and ignores default config files.) The file can be either in JSON format or a JavaScript module that exports the configuration object:

**JSON configuration example:**

```json
{
  "collapseWhitespace": true,
  "removeComments": true,
  "fileExt": "html,php",
  "ignoreDir": "libs,vendor"
}
```

For editor support (validation, autocomplete, and inline documentation) in JSON configuration files, reference the [JSON Schema](https://raw.githubusercontent.com/j9t/html-minifier-next/main/html-minifier-next.schema.json) that ships with the package:

```json
{
  "$schema": "https://raw.githubusercontent.com/j9t/html-minifier-next/main/html-minifier-next.schema.json",
  "collapseWhitespace": true,
  "removeComments": true
}
```

(If HMN is installed locally, you can also use the path ./node_modules/html-minifier-next/html-minifier-next.schema.json instead of the URL.)

**JavaScript module configuration example** (requires `"type": "module"` in the project’s package.json, or use a .mjs extension):

```js
export default {
  collapseWhitespace: true,
  removeComments: true,
  fileExt: "html,php",
  ignoreDir: ["libs", "vendor"]
};
```

A module can also hold values JSON cannot express, like regular expressions (e.g., `ignoreCustomFragments: [/\{\{[\s\S]*?\}\}/]`) and functions (for `minifyCSS`, `minifyJS`, and `minifyURLs`, or in custom SVGO plugins for `minifySVG`). As functions cannot be passed to worker threads, a run using them minifies in-process.

### Node.js

```js
import { minify } from 'html-minifier-next';

const result = await minify('<p title="example" id="moo">foo</p>', {
  removeAttributeQuotes: true,
  removeOptionalTags: true
});
console.log(result); // `<p title=example id=moo>foo`
```

(CommonJS consumers can still use dynamic import—`const { minify } = await import('html-minifier-next')`—as `minify()` is async.)

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`: Basic minification with whitespace collapsing, comment removal, and removal of select attributes.
* `comprehensive`: More advanced minification for better file size reduction, including 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.

**Using presets:**

```shell
# Via CLI flag
npx html-minifier-next --preset conservative input.html

# Via config file
npx html-minifier-next --config-file=path/to/config.json input.html
# where config.json contains `{ "preset": "conservative" }`

# Override preset options
npx html-minifier-next --preset conservative --remove-empty-attributes input.html
```

**Priority order:** Presets are applied first, then config file options, then CLI flags. This allows you to start with a preset and customize as needed.

## Options quick reference

Most of the options are disabled by default. Experiment and find what works best for you and your project.

Options can be used in config files (camelCase) or via CLI flags (kebab-case with `--` prefix). Boolean options generally support both `--option-name` to enable and `--no-option-name` to disable, so you can override a preset or config file from the command line. (Exception: Options whose name already starts with `no-`, such as `noNewlinesBeforeTagClose`, only expose the `--no-…` CLI flag.)

| Option (config/CLI) | Description | Default |
| --- | --- | --- |
| `cacheCSS`<br>`--cache-css` | Set CSS minification cache size; higher values improve performance for batch processing | `500` |
| `cacheJS`<br>`--cache-js` | Set JavaScript minification cache size; higher values improve performance for batch processing | `500` |
| `cacheSVG`<br>`--cache-svg` | Set SVG minification cache size; higher values improve performance for batch processing | `500` |
| `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` | Collapse whitespace more aggressively between inline elements—use with [`collapseWhitespace`](#combining-whitespace-options) | `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); [enable other whitespace options](#combining-whitespace-options) | `false` |
| `conservativeCollapse`<br>`--conservative-collapse` | Always collapse to one space (never remove it entirely)—use with [`collapseWhitespace`](#combining-whitespace-options) | `false` |
| `continueOnMinifyError`<br>`--continue-on-minify-error`<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` | 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 (e.g., `ng-click`)—use with `minifyJS` | `[ /^on[a-z]{3,}$/ ]` |
| `decodeEntities`<br>`--decode-entities` | Use direct Unicode characters whenever possible | `false` |
| `ignoreCustomComments`<br>`--ignore-custom-comments` | Array of regexes that allow to ignore matching comments | `[ /^!/, /^\s*#/ ]` |
| `ignoreCustomFragments`<br>`--ignore-custom-fragments` | Array of regexes that allow to ignore certain fragments, when matched (e.g., `<?php … ?>`, `{{ … }}`, etc.) | `[ /<%[\s\S]*?%>/, /<\?[\s\S]*?\?>/ ]` |
| `includeAutoGeneratedTags`<br>`--include-auto-generated-tags` | Insert elements generated by HTML parser | `false` |
| `inlineCustomElements`<br>`--inline-custom-elements` | Array of names of custom elements which are inline, for whitespace handling—use with `collapseWhitespace` | `[]` |
| `keepClosingSlash`<br>`--keep-closing-slash` | Keep the trailing slash on void elements and other start tags that carry one, and read it as closing the element | `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 | `undefined` |
| `mergeScripts`<br>`--merge-scripts` | Merge consecutive inline `script` elements into one (only merges compatible scripts with same `type`, matching `async`/`defer`/`nomodule`/`nonce`) | `false` |
| `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://terser.org/) or [SWC](https://swc.rs/)) | `false` (could be `true`, `Object`, `Function(text, inline)`) |
| `minifySVG`<br>`--minify-svg` | Minify SVG elements (uses [SVGO](https://svgo.dev/)) | `false` (could be `true`, `Object`) |
| `minifyURLs`<br>`--minify-urls` | Minify URLs in various attributes | `false` (could be `true`, `String`, `Object`, `Function(text)`) |
| `noNewlinesBeforeTagClose`<br>`--no-newlines-before-tag-close` | Never add a newline before a tag that closes an element—use with `maxLineLength` | `false` |
| `partialMarkup`<br>`--partial-markup` | Treat input as a partial HTML fragment, preserving stray end tags (closing tags without opening tags) and preventing auto-closing of unclosed tags at end of input | `false` |
| `preserveLineBreaks`<br>`--preserve-line-breaks` | Always collapse to one line break (never remove it entirely) when whitespace between tags includes a line break—use with [`collapseWhitespace`](#combining-whitespace-options) | `false` |
| `preventAttributesEscaping`<br>`--prevent-attributes-escaping` | Prevents the escaping of the values of attributes | `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` |
| `removeDefaultTypeAttributes`<br>`--remove-default-type-attributes` | Remove default `type` attributes from `style`/`link` (e.g., `type="text/css"`) and `script` (e.g., `type="text/javascript"`) elements; other `type` attribute values are left intact | `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—use with `removeEmptyElements`; 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` |
| `removeRedundantAttributes`<br>`--remove-redundant-attributes` | [Remove attributes when value matches default](https://meiert.com/blog/optional-html/#toc-attribute-values) | `false` |
| `removeTagWhitespace`<br>`--remove-tag-whitespace` | Remove space between attributes whenever possible; **note that this will result in invalid HTML** | `false` |
| `removeUnusedCSS`<br>`--remove-unused-css` | [Remove unused CSS rules](#unused-css-removal) from `style` elements—use with `minifyCSS`; **note that this can change how a document renders** | `false` (could be `true`, `{ safelist, scripts }`) |
| `sortAttributes`<br>`--sort-attributes` | [Sort attributes by frequency](#sorting-attributes-and-style-classes) | `false` |
| `sortClassNames`<br>`--sort-class-names` | [Sort style classes by frequency](#sorting-attributes-and-style-classes) | `false` |
| `strictCustomFragments`<br>`--strict-custom-fragments` | [Reject `ignoreCustomFragments` patterns that risk catastrophic backtracking](#redos-protection) (rather than warning about them) | `false` |
| `trimCustomFragments`<br>`--trim-custom-fragments` | Trim whitespace around custom fragments (`ignoreCustomFragments`)—use with `collapseWhitespace` | `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` |

### API-only options

A few options take functions and are therefore only available programmatically, not via CLI flags or config files:

| Option | Description | Default |
| --- | --- | --- |
| `canCollapseWhitespace` | `Function(tag, attrs, defaultFn)` that determines whether whitespace inside an element can be collapsed—override to protect additional elements, delegating to `defaultFn` for the rest | Built-in handling (protects `pre`, `textarea`, etc.) |
| `canTrimWhitespace` | `Function(tag, attrs, defaultFn)` that determines whether leading and trailing whitespace around an element may be trimmed | Built-in handling |
| `log` | `Function(message)` called with warnings and errors, including minification errors swallowed by `continueOnMinifyError` (e.g., pass `console.error` to surface them); the CLI wires this up under `--verbose` and `--dry` | No-op (errors are silent) |

### Options that rely on another option

Some options modify what another option does, and do nothing when that other option is off. Setting one on its own is reported through [the `log` hook](#api-only-options) (and, in the CLI, on STDERR), once per message per run:

```text
HTML Minifier Next: Ignoring `conservativeCollapse`—use with `collapseWhitespace` (`--collapse-whitespace`)
```

| Option | Needs |
| --- | --- |
| `collapseInlineTagWhitespace` | `collapseWhitespace` |
| `conservativeCollapse` | `collapseWhitespace` |
| `customEventAttributes` | `minifyJS` |
| `inlineCustomElements` | `collapseWhitespace` |
| `noNewlinesBeforeTagClose` | `maxLineLength` |
| `preserveLineBreaks` | `collapseWhitespace` |
| `removeEmptyElementsExcept` | `removeEmptyElements` |
| `removeUnusedCSS` | `minifyCSS`, and not [a function of your own](#unused-css-removal) |
| `trimCustomFragments` | `collapseWhitespace` |

Passing the option `false`, or an empty array, asks for nothing and is not reported. `cacheCSS`, `cacheJS`, and `cacheSVG` are not listed: They size a cache rather than transform markup, and don’t change output.

### Combining whitespace options

`collapseInlineTagWhitespace`, `conservativeCollapse`, and `preserveLineBreaks` are modifiers: They do nothing on their own, and only take effect when `collapseWhitespace` is enabled.

Given input

```html
<nav>
  <button>A</button> <button>B</button>
</nav>
```

you get the following output (condensed, `\n` represents an actual line break):

| Options | Output |
| --- | --- |
| `collapseInlineTagWhitespace` | `<nav>\n  <button>A</button> <button>B</button>\n</nav>` (unchanged) |
| `collapseWhitespace` | `<nav><button>A</button> <button>B</button></nav>` |
| `collapseWhitespace`, `collapseInlineTagWhitespace` | `<nav><button>A</button><button>B</button></nav>` |
| `collapseWhitespace`, `conservativeCollapse` | `<nav> <button>A</button> <button>B</button> </nav>` |
| `collapseWhitespace`, `preserveLineBreaks` | `<nav>\n<button>A</button> <button>B</button>\n</nav>` |
| `collapseWhitespace`, `preserveLineBreaks`, `collapseInlineTagWhitespace` | `<nav>\n<button>A</button><button>B</button>\n</nav>` |

Where the modifiers disagree, the preserving one wins—`conservativeCollapse` and `preserveLineBreaks` do not let `collapseInlineTagWhitespace` remove a space or line break entirely.

### Sorting attributes and style classes

Minifier options like `sortAttributes` and `sortClassNames` won’t impact the plain-text size of the output. However, `sortAttributes` (but not `sortClassNames`) improves the compression ratio for Gzip and Brotli used over HTTP.

### CSS minification

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:

```js
const result = await minify(html, {
  minifyCSS: {
    targets: {
      // Browser targets for vendor prefix handling
      chrome: 95,
      firefox: 90,
      safari: 14
    },
    unusedSymbols: ['unused-class', 'old-animation']
  }
});
```

Available Lightning CSS options when passed as an object:

* `targets`: Browser targets for vendor prefix optimization (e.g., `{ chrome: 95, firefox: 90 }`).
* `unusedSymbols`: Array of class names, IDs, keyframe names, and CSS variables to remove.
* `errorRecovery`: Boolean to skip invalid rules instead of throwing errors. This is disabled by default in Lightning CSS, but enabled in HMN when the `continueOnMinifyError` option is set to `true` (the default). Explicitly setting `errorRecovery` in `minifyCSS` options will override this automatic behavior. What Lightning CSS takes issue with is reported through [the `log` hook](#api-only-options)—it drops some of it (`@property` with an invalid `syntax`) and passes the rest through (an unknown at-rule), so that a dropped rule does not go unnoticed. Every document is reported on separately.
* `sourceMap`: Boolean to generate source maps.

For advanced usage, you can also pass a function:

```js
const result = await minify(html, {
  minifyCSS: function(text, type) {
    // `text`: CSS string to minify
    // `type`: `inline` for style attributes, `media` for media queries, `undefined` for `<style>` elements
    return yourCustomMinifier(text);
  }
});
```

### Unused CSS removal

`removeUnusedCSS` removes rules from `style` elements whose class or ID selectors the document doesn’t reference. It needs to be used with `minifyCSS`, because the removal runs through Lightning CSS—passing `minifyCSS` a function of your own replaces that step, so the removal does not apply, either. Both cases are reported through [the `log` hook](#api-only-options). It does not touch `style` or `media` attributes.

```js
const result = await minify(html, {
  minifyCSS: true,
  removeUnusedCSS: true
});
```

Symbols are considered used when they appear

* in a `class` or `id` attribute,
* in an attribute that references an ID (`for`, `headers`, `list`, `popovertarget`, `aria-controls`, and similar),
* in a same-document fragment URL, as `href="#main"`, `<use href="#icon">`, or `usemap="#map"`, and in a `url(#gradient)` reference from any attribute,
* anywhere in a `data-*` attribute value, or
* anywhere inside an inline `script` element, unless `scripts` is set to `false`.

Names carrying characters that end a CSS identifier—`md:flex`, `w-1/2`, `p-[3px]`—are matched as whole tokens, so utility-CSS class names survive whether they come from markup, a `data-*` value, or a string in an inline script.

**Class names that only appear in external scripts cannot be detected.** A minifier sees one document, not the DOM that scripts later build from it, so a class added by bundle.js looks exactly like a class nobody uses. List those under `safelist`, as strings or regular expressions:

```js
const result = await minify(html, {
  minifyCSS: true,
  removeUnusedCSS: {
    safelist: ['is-open', /^js-/],
    // Set to `false` to also drop rules only referenced from inline scripts
    scripts: true
  }
});
```

Names used by `@keyframes` and `@counter-style` rules are not removed, even when no element carries them as a class or ID, since those at-rules are referenced from CSS rather than from markup.

Values that cannot be honored—a `safelist` that isn’t an array, an entry that is neither a string nor a regular expression, a misspelled key—are reported through the `log` hook.

### JavaScript minification

When `minifyJS` is set to `true`, HTML Minifier Next uses [Terser](https://terser.org/) by default to minify JavaScript in `<script>` elements and event attributes.

You can choose between different JS minifiers using the `engine` field:

```js
const result = await minify(html, {
  minifyJS: {
    engine: 'swc', // Use SWC for faster minification
    // SWC-specific options here
  }
});
```

**Available engines:**

* `terser` (default): The standard JavaScript minifier with excellent compression
* [`swc`](https://swc.rs/): Rust-based minifier multiple times faster than Terser (requires separate installation)

The engine also decides how work is scheduled: SWC minifies a document’s script bodies as one batch dispatched ahead of the parse, while Terser shares the thread the parse runs on.

**To use SWC**, install it as a development dependency:

```shell
npm i -D @swc/core
```

**Important:** Inline event handlers (e.g., `onclick="return false"`) always use Terser regardless of the `engine` setting, as SWC doesn’t support bare return statements. This is handled automatically—you don’t need to do anything special.

You can pass engine-specific configuration options:

```js
// Using Terser with custom options
const result = await minify(html, {
  minifyJS: {
    compress: {
      drop_console: true  // Remove console.log statements
    }
  }
});

// Using SWC for faster minification
const result = await minify(html, {
  minifyJS: {
    engine: 'swc'
  }
});
```

For advanced usage, you can also pass a function:

```js
const result = await minify(html, {
  minifyJS: function(text, inline) {
    // `text`: JavaScript string to minify
    // `inline`: `true` for event handlers (e.g., `onclick`), `false` for `<script>` elements
    return yourCustomMinifier(text);
  }
});
```

### SVG minification

When `minifySVG` is set to `true`, HTML Minifier Next uses [SVGO](https://svgo.dev/) to optimize inline SVG elements. Complete `<svg>` subtrees are extracted and processed as a block, enabling deep structural optimization:

```js
const result = await minify(html, {
  minifySVG: true // Enable with SVGO defaults fit for inline SVG
});
```

Unlike an SVG file, an inline SVG is part of the page. HMN runs SVGO’s `preset-default` with the plugins that assume a standalone file turned off (see overrides below). `style` elements in SVG are minified through `minifyCSS` and SVGO.

You can pass custom SVGO options. Options without `plugins` (e.g., `{ floatPrecision: 2 }`) keep HMN’s plugin set; options with `plugins` replace it, so include the overrides for inline SVG unless the SVGs don’t depend on the rest of the page:

```js
const result = await minify(html, {
  minifySVG: {
    plugins: [{
      name: 'preset-default',
      params: {
        overrides: {
          // Inline SVG
          cleanupIds: false,
          inlineStyles: false,
          minifyStyles: { usage: false },
          removeHiddenElems: false,
          removeUnknownsAndDefaults: { keepRoleAttr: true },
          // Custom
          convertShapeToPath: false // Keep original shapes
        }
      }
    }]
  }
});
```

**Important:**

* SVG minification only applies within `<svg>` elements
* Case sensitivity and self-closing slashes are automatically preserved in SVG (regardless of global settings); where SVGO reads, names are written the way HTML reads them (e.g., `viewbox` as `viewBox`)
* For maximum compression, use `minifySVG` together with `collapseWhitespace` and other options

### CSS, JavaScript, and SVG cache configuration

HTML Minifier Next uses in-memory caches to improve performance when processing multiple files or repeated content. The cache sizes can be configured for optimal performance based on your use case:

```js
const result = await minify(html, {
  minifyCSS: true,
  minifyJS: true,
  minifySVG: true,
  // Configure cache sizes (in number of entries)
  cacheCSS: 750,  // CSS cache size, default: 500
  cacheJS: 250,   // JS cache size, default: 500
  cacheSVG: 100   // SVG cache size, default: 500
});
```

**Via CLI flags:**

```shell
npx html-minifier-next --minify-css --cache-css 750 --minify-js --cache-js 250 --minify-svg --cache-svg 100 input.html
```

**Via environment variables:**

```shell
export HMN_CACHE_CSS=750
export HMN_CACHE_JS=250
export HMN_CACHE_SVG=100
npx html-minifier-next --minify-css --minify-js --minify-svg input.html
```

**Configuration file:**

```json
{
  "minifyCSS": true,
  "cacheCSS": 750,
  "minifyJS": true,
  "cacheJS": 250,
  "minifySVG": true,
  "cacheSVG": 100
}
```

**When to adjust cache sizes:**

* Single file processing: Default `500` is sufficient
* Batch processing: Increase to `1000` or higher for better cache hit rates
* Memory-constrained environments: Cache sizes can be lowered, though the savings are usually negligible—entries are typically kilobyte-scale, so even full caches only hold a few megabytes
* Hundreds/thousands of files: Increase to `1000`–`2000` for optimal performance

**Important:**

* Cache locking: Caches are created on the first `minify()` call and persist for the process lifetime. Cache sizes are locked after first initialization—subsequent calls reuse the same caches even if different `cacheCSS`, `cacheJS`, or `cacheSVG` options are provided. The first call’s options determine the cache sizes.
* Values: `0` switches the cache off; negative and non-finite values fall back to the default size.
* Entry size cap: Individual CSS, JavaScript, or SVG blocks larger than 1 MB are minified normally but not stored in the cache—this bounds worst-case cache memory without affecting realistically sized inline content. (This cutoff is fixed and not configurable.)

The caches persist across multiple `minify()` calls, making them particularly effective when processing many files in a batch operation.

**Inspecting cache effectiveness:**

Use `getCacheStats()` to see hit/miss counts and current occupancy for each cache:

```js
import { minify, getCacheStats } from 'html-minifier-next';

// After minifying pages that share templated CSS/JS…
for (const html of pages) {
  await minify(html, { minifyCSS: true, minifyJS: true });
}

console.log(getCacheStats());
// {
//   css: { gets: 392, hits: 298, size: 94, limit: 500 },
//   js: { gets: 1196, hits: 1192, size: 4, limit: 500 },
//   svg: { gets: 0, hits: 0, size: 0, limit: 500 }
// }
```

A cache that was never exercised (e.g., `minifySVG` disabled, or `minify()` not yet called) reports all-zero stats.

The CLI’s `--verbose` and `--dry` modes print the same information to STDERR at the end of a run, omitting caches that were never touched.

## Minification comparison

Please see [**the Minifier Benchmarks project**](https://github.com/j9t/minifier-benchmarks) for details on how HTML Minifier Next compares to other minifiers. (The benchmarks are currently maintained by the author of HTML Minifier Next. Contributions, including from other minifier authors, are welcome.)

## Examples

### CLI

**Sample command line:**

```shell
npx html-minifier-next --collapse-whitespace --remove-comments --minify-js --input-dir=. --output-dir=example

npx html-minifier-next --input-dir=test --preset comprehensive --output-dir example
```

**Process specific files and directories:**

```shell
# Process default extensions (html, htm, shtml, shtm)
npx html-minifier-next --collapse-whitespace --input-dir=src --output-dir=dist

# Process only specific extensions
npx html-minifier-next --collapse-whitespace --input-dir=src --output-dir=dist --file-ext=html,php

# Using a configuration file that sets `fileExt` (e.g., `"fileExt": "html,php"`)
npx html-minifier-next --config-file=path/to/config.json --input-dir=src --output-dir=dist

# Process all files (explicit wildcard)
npx html-minifier-next --collapse-whitespace --input-dir=src --output-dir=dist --file-ext='*'
```

**Exclude directories from processing:**

```shell
# Ignore a single directory
npx html-minifier-next --collapse-whitespace --input-dir=src --output-dir=dist --ignore-dir=libs

# Ignore multiple directories
npx html-minifier-next --collapse-whitespace --input-dir=src --output-dir=dist --ignore-dir=libs,vendor,node_modules

# Ignore by relative path (only ignores src/static/libs, not other “libs” directories)
npx html-minifier-next --collapse-whitespace --input-dir=src --output-dir=dist --ignore-dir=static/libs
```

**Dry run mode (preview outcome without writing files):**

```shell
# Preview with output file
npx html-minifier-next input.html -o output.html --dry --collapse-whitespace

# Preview directory processing with statistics per file and total
npx html-minifier-next --input-dir=src --output-dir=dist --dry --collapse-whitespace
# Output: [DRY RUN] Would process directory: src → dist
#   index.html: 1,234 → 892 bytes (-342, 27.7%)
#   about.html: 2,100 → 1,654 bytes (-446, 21.2%)
# ---
# Total: 3,334 → 2,546 bytes (-788, 23.6%)
```

**Verbose mode (show detailed processing information):**

```shell
# Show processing details while minifying
npx html-minifier-next --input-dir=src --output-dir=dist --verbose --collapse-whitespace
# Output: CLI options: collapseWhitespace
#   ✓ src/index.html: 1,234 → 892 bytes (-342, 27.7%)
#   ✓ src/about.html: 2,100 → 1,654 bytes (-446, 21.2%)
# ---
# Total: 3,334 → 2,546 bytes (-788, 23.6%)

# `--dry` automatically enables verbose output
npx html-minifier-next --input-dir=src --output-dir=dist --dry --collapse-whitespace
```

## Special cases

### Ignoring chunks of markup

If you have chunks of markup you would like preserved, you can wrap them with `<!-- htmlmin:ignore -->`.

### Minifying JSON content

JSON script types are minified automatically without configuration, including `application/json`, `application/ld+json`, `application/manifest+json`, `application/vnd.geo+json`, `application/problem+json`, `application/merge-patch+json`, `application/json-patch+json`, `importmap`, and `speculationrules`. Malformed JSON is preserved by default (with `continueOnMinifyError: true`).

Note: The `processScripts` option is only for script types containing HTML templates (e.g., `text/ng-template`, `text/x-handlebars-template`), not for JSON.

### Preserving SVG and MathML elements

SVG and MathML elements are automatically recognized as foreign elements, and when they are minified, both case-sensitivity and self-closing slashes are preserved, regardless of the minification settings used for the rest of the file. This ensures valid output for these namespaced elements.

### Working with invalid or partial markup

By default, HMN parses markup into a complete tree structure, then modifies it (removing anything that was specified for removal, ignoring anything that was specified to be ignored, etc.), then creates markup from that tree and returns it.

_Input markup (e.g., `<p id="">foo`) → Internal representation of markup in a form of tree (e.g., `{ tag: "p", attr: "id", children: ["foo"] }`) → Transformation of internal representation (e.g., removal of `id` attribute) → Output of resulting markup (e.g., `<p>foo</p>`)_

For partial HTML fragments (such as template includes, SSI fragments, or closing tags without opening tags), use the `partialMarkup: true` option. This preserves stray end tags (closing tags without corresponding opening tags) and prevents auto-closing of unclosed tags at the end of input. Note that normal HTML auto-closing rules still apply during parsing—for example, a closing parent tag will still auto-close its unclosed child elements.

To validate complete HTML markup, use [the W3C validator](https://validator.w3.org/) or one of [several validator packages](https://meiert.com/blog/html-validator-packages/).

### Regex options and flags

`customAttrAssign` and `customAttrSurround` patterns are merged into one attribute pattern which carries no flags of its own. `i` and `s` are written into each pattern’s source instead, so they survive the merge. `u`, `v`, and `m` cannot be, and none of them fails loudly when dropped: `u` and `v` only narrow what syntax is legal, so a source valid under either stays valid without it and quietly matches something else—a dropped `u` leaves `\p{L}` matching the literal text `p{L}`—while a dropped `m` leaves `^` and `$` matching at the ends of the input rather than of each line.

A pattern is therefore refused with an error where the flag changes what its source matches—a property or code point escape, a character past the BMP, a character `i` folds by Unicode rules only while `u` is there (`/s/iu` matches `\u017F`, `/k/iu` matches `\u212A`), a `v` class that nests, subtracts, intersects, or holds strings, or—under `m`—an anchor whose meaning moves. A flag the source does not depend on, as in `/x=/u`, is left alone.

Patterns given as strings, in a configuration file or on the command line, may be written either bare (`ng-class`) or delimited with flags (`/ng-class/i`).

## Security

### ReDoS protection

You can use `ignoreCustomFragments` to hand HTML Minifier Next a regular expression to run against your documents. This is also where a regular expression denial of service (ReDoS) could originate:

* Matching without backtracking: A pattern that wraps an any-character or negated-class body in literal delimiters—`<%[\s\S]*?%>` or `\{\{[^}]*?\}\}`, and every other shape below—is matched by scanning for those delimiters in linear time, with no regular expression involved. Patterns of other shapes run as regular expressions, one per pattern, so each keeps its own flags.

* Pattern detection: HMN warns about the shapes that backtrack catastrophically—an unlimited quantifier over a group that itself contains a quantifier that can vary (`(a+)+`, `(a?)+`) or alternation (`(a|b)*`), and two unbounded repeats that can consume the same character with only atoms matching empty between them (`.*.*`, `[a]*a*`, `\w*\d*`, `a*b*a*`).

  A group is no wall: It counts by what its body can match, and repeats meet across its boundary, so `\s*(\w*)\s*` and `(a*)a*` are flagged like `\s*\w*\s*` and `a*a*`. A lookaround backtracks nothing, so `(?=a*)a*` passes. A fixed count does not vary, so `(?:a{4})+` passes; repeats that share no character leave nothing ambiguous to split, so `\s*\S*` passes. A pattern is read the way its own flags make it match, so `/.*\n*/s` and `/[a]*A*/i` are flagged where those same sources without the flags are not. Under `v`, a class that nests reads as the union it is, while one that subtracts (`--`) or intersects (`&&`) is left unread and passes.

  These are also shapes a linear scan cannot stand in for. `strictCustomFragments` refuses them with an error instead, which is worth enabling where the patterns or the input are not entirely under your control. A pattern longer than 10,000 characters or nested more than 50 groups deep is judged risky without being analyzed further, so that reading the pattern cannot itself become the expensive step. The check reads shapes, not languages: It warns about the common ones rather than proving a pattern linear, and misses repeats that overlap only across whole subexpressions (`(ab)*(abab)*`). **Treat a pattern that passes as unflagged, not as vetted.**

* Input length limits: The `maxInputLength` option allows you to set a maximum input size to prevent processing of excessively large inputs that could cause performance issues.

**Important:** A single unlimited quantifier is not one of those shapes: `[\s\S]*?` running up to a literal terminator matches in linear time, and it is how HMN’s defaults are written. Bounds are still worth adding where you know the maximum length of a fragment, since they cap how far a failing match can scan.

#### Custom fragment examples

**Safe patterns:**

```js
ignoreCustomFragments: [
  /<%[\s\S]*?%>/,                // Lazy scan up to a literal terminator
  /<\?php[\s\S]{0,5000}?\?>/,    // PHP with explicit bounds
  /\{\{[^}]{0,500}\}\}/          // Handlebars without nested braces
]
```

**Unsafe patterns** (these trigger warnings):

```js
ignoreCustomFragments: [
  /<%(\s|\S)*?%>/,               // Unlimited quantifier over an alternating group
  /\{\{([^}]+)+\}\}/,            // Nested unlimited quantifiers
  /<!--[\s\S]*[\s\S]*-->/,       // Two unbounded repeats in a row
  /<%\w*\d*%>/                   // Two unbounded repeats over overlapping sets
]
```

**Template engine configurations:**

```js
// Handlebars/Mustache
ignoreCustomFragments: [/\{\{[\s\S]{0,1000}?\}\}/]

// Liquid (Jekyll)
ignoreCustomFragments: [/\{%[\s\S]{0,500}?%\}/, /\{\{[\s\S]{0,500}?\}\}/]

// Angular
ignoreCustomFragments: [/\{\{[\s\S]{0,500}?\}\}/]

// Vue.js
ignoreCustomFragments: [/\{\{[\s\S]{0,500}?\}\}/]
```

##### 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):**

```js
ignoreCustomFragments: [/\{%[\s\S]{0,1000}?%\}/, /\{\{[\s\S]{0,500}?\}\}/]
```

**CLI (via config file—recommended):**

```shell
npx html-minifier-next --config-file=path/to/config.json input.html
```

**CLI (inline—not recommended due to complex escaping):**

```shell
npx 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/)**

```text
\{%[\s\S]{0,1000}?%\} \{\{[\s\S]{0,500}?\}\}
```

## Working on HTML Minifier Next

Note: This section assumes working with main dependencies installed (`npm i`).

### Local server

```shell
npm run serve
```

### Regression tests

```shell
cd backtest;
npm i;
npm run backtest
```

The backtest tool tracks minification performance across Git history. Results are saved in the backtest folder as a JSON file, results.json.

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)

### Working tree benchmarks

Where the backtest walks Git history, the benchmark times the code as it is _right now_—useful for A/B testing a branch against a saved baseline:

```shell
cd backtest;
npm i;
npm run benchmark
```

It reuses the backtest corpus (run `npm run backtest` once to download it) and reports per-file output size and processing time.

Parameters:

* No argument: Runs and, if a baseline exists, shows size and time deltas
* `--save`: Saves the run as the baseline (e.g., on `main` before switching to a branch)
* `--core`: Disables the external minifiers (CSS, JS, SVG, URLs) to isolate HMN’s processing time
* `--cold`: Switches the minification caches off so CSS, JS, and SVG work is redone on every iteration—without it, warm caches serve those results from memory after the warm-up run and the benchmark cannot see changes to those minifiers
* `--iterations=N`: Sets the number of timed iterations (default: 5)
* `--config=PATH`: Uses an alternative options file (default: html-minifier-next.config.json)

To compare branches (A/B run), execute `npm run benchmark -- --save` on `main`, then `npm run benchmark` on the branch to see the deltas. Add `--core` on both ends when measuring changes to HMN rather than bundled minifiers, or `--cold` when measuring changes to the CSS, JS, or SVG minification paths.

Reported times are the *fastest* iteration, not the median: Interference can only make a run slower, so the minimum is the most stable estimate. Each run also reports its noise—how far the reported figure moves between the first and second half of the iterations—and any delta smaller than that is marked `within noise` rather than shown as a win or a regression. Raise `--iterations` until the noise sits below the change you are trying to measure.

#### Profiling

To profile the current working tree, run the benchmark with Node’s built-in CPU profiler:

```shell
node --cpu-prof benchmark.js
```

This writes a .cpuprofile file to the working directory. Load it with `npx speedscope *.cpuprofile` for a flamegraph, or drag it into Chrome DevTools → Sources → JavaScript Profiler. Compare self-time per function against a clean baseline run on `main`. Pay attention to unexpectedly heavy callbacks in hot paths—V8 de-optimization from variable object shapes or unnecessary method calls can show up there.

## Acknowledgements

With many thanks to the previous authors of and contributors to 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), [Jonas Geiler](https://github.com/jonasgeiler), and [Chris Morgan](https://github.com/chris-morgan)!

***

You might like some of my other work:

* Optimization tools: [hihtml](https://github.com/j9t/hihtml) · HTML Minifier Next · [ObsoHTML](https://github.com/j9t/obsohtml) · [CSS Dedup](https://github.com/j9t/css-dedup) · [Image Guard](https://github.com/j9t/image-guard) · [Compressor.js Next](https://github.com/j9t/compressorjs-next) · [.htaccess Punk](https://github.com/j9t/htaccess-punk)
* Defense tools: [IA Defensa](https://iadefensa.com/solutions/)
* Resources for quality web development: [Articles](https://meiert.com/topics/development/) · [Books](https://meiert.com/topics/books/) (including [_On Web Development_](https://meiert.com/blog/on-web-development-2/)) · [News](https://frontenddogma.com/) · [Terminology](https://webglossary.info/)

---
_Source: https://npm.io/package/html-minifier-next · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._