# kangax/html-minifier: a configurable HTML minifier whose README now points elsewhere

> The original JavaScript HTML minifier still installs from npm and still exposes dozens of options, but its own README tells you to use HTML Minifier Next instead. Here is what that means for a build pipeline.

**kangax/html-minifier** — Javascript-based HTML compressor/minifier (with Node.js support)

- Repository: https://github.com/kangax/html-minifier
- Website: http://kangax.github.io/html-minifier/
- Stars: 5,032 · Forks: 577
- Language: JavaScript
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/kangax-html-minifier

## The problem kangax/html-minifier solves, and for whom

HTML arrives at the browser with whitespace, comments, optional quotes and optional closing tags that a parser does not need. kangax/html-minifier removes them without changing the document tree. The README describes it as a "highly configurable, well-tested, JavaScript-based HTML minifier", and the configuration surface is the point: the options table lists more than thirty flags, and most are disabled by default.

That default matters more than any single option. A pipeline that installs the package and calls it with no options gets comment stripping and not much else. The large reductions in the README's comparison table come from turning things on deliberately, which means the tool rewards a team that reads the table and punishes one that does not.

The audience is narrow and specific. This is for Node.js build pipelines that emit static HTML: server-side rendered pages, documentation sites, email templates compiled ahead of time. It is not a runtime middleware by itself, although the README points to Koa and Express wrappers, and it is not a browser tool, although the repository ships a dist/ directory and a hosted test suite.

## How the minifier actually processes a document

The pipeline is parse, transform, serialize. package.json lists the runtime dependencies that do the work: he for entity handling, clean-css for embedded stylesheets, uglify-js for embedded scripts, relateurl for URL rewriting, plus camel-case and param-case for attribute name handling. Each of those maps to an option group, which is why the option table is as long as it is.

The interaction between options is where the design shows its age. collapseInlineTagWhitespace is documented as usable only together with collapseWhitespace=true, and conservativeCollapse likewise requires collapseWhitespace=true. Those are not independent switches; they are modifiers on a mode. Setting one without the other does nothing useful, and the README states the dependency rather than enforcing it at runtime.

The escape hatches are the most interesting part. ignoreCustomComments takes an array of regular expressions and defaults to [ /^!/ ], so conditional comments survive by default. ignoreCustomFragments does the same for template syntax, and customAttrSurround and customAttrAssign exist for templating dialects that put expressions inside attribute positions. A minifier that only understood well-formed HTML would break every Handlebars or Angular template it touched; these options are the acknowledgement that real input is not clean.

## Installing from npm and running the CLI once

The package is published on npm as html-minifier and exposes a binary named html-minifier through the bin field, which package.json maps to ./cli.js. package.json requires Node.js 10 or later, so any current LTS satisfies it. The README's installation route is the npm package:

```bash
npm install html-minifier
```

The repository ships sample-cli-config-file.conf, a config file the CLI can consume so you do not retype flags on every build. The README's options table is the reference for what belongs in it, and the hosted test suite linked from the project homepage is where you check what a given option does to a specific construct before committing to it.

One thing to watch before you wire this into a build: most options are disabled by default, so a run with no configuration is close to a no-op apart from comment handling. Check the output size against the input on one real page before assuming the pipeline is doing anything.

## Where the option model breaks down

The failure mode is not a crash. It is output that parses differently from the input, discovered later, in production.

collapseWhitespace is the sharp edge. Whitespace between inline elements is significant in HTML, and collapsing it changes rendering for any layout that depends on a literal space between two inline tags. The README's own answer is collapseInlineTagWhitespace, which is documented as removing spaces between display:inline elements entirely. That is a stronger transformation, not a safer one, and it is opt-in for a reason.

continueOnParseError is the second sharp edge, and it cuts the other way. By default the minifier aborts on a parse error, which is the behaviour you want in a build: a malformed template should fail the build, not ship subtly truncated. Setting continueOnParseError to true trades that safety for throughput on input you know is dirty. Teams reach for it to make a red build go green, which is the opposite of what it is for.

There is also a structural limit. The README states plainly that this version is no longer maintained and points to HTML Minifier Next for "new features and critical security fixes". Everything in the options table describes v4.0.0, released on 2019-04-01. If you need a fix that landed after that, it is not here.

## HTML Minifier Next and the wrapper packages

The README's first section is an instruction, not a disclaimer: use HTML Minifier Next (HMN) from j9t for an up-to-date version with new features and critical security fixes. That is the maintainers telling you where the work continues. The difference in approach is maintenance rather than mechanism; both are JavaScript HTML minifiers with an option table, and HMN is the one receiving changes.

Alternatives inside the same ecosystem are mostly packaging. The README lists a Grunt plugin (grunt-contrib-htmlmin), a Gulp module (gulp-htmlmin), a Koa middleware wrapper and an Express middleware wrapper (express-minify-html), plus a Ruby wrapper. Those do not change the minification algorithm; they change where you call it from. If your build already runs Grunt or Gulp, adopting the wrapper is less work than wiring the CLI into a task.

The README's comparison table sets it against minimize, the Will Peavy minifier and htmlcompressor.com across thirteen sites, with html-minifier producing the smallest output on every row where a figure is given. That table is from the project's own documentation and reflects the version it was measured against, so treat it as the maintainers' claim rather than an independent result.

For embedded assets, the split is clean: this tool delegates CSS to clean-css and JavaScript to uglify-js. If your JavaScript minification already runs through a separate step, disable the embedded minification here and let the dedicated tool own it, rather than running two minifiers over the same script.

## Maintenance, licence and the cost of staying

The repository is not archived and its last push was on 2026-03-26, but the README states the version is no longer maintained. Those two facts sit together: the repository receives activity while the published line does not. The latest release is v4.0.0 from 2019-04-01, preceded by v3.5.20 in 2018 and v3.5.19 in 2018. Anyone pinning to the npm package is pinning to a 2019 artifact.

The upgrade cost is therefore not a version bump. It is a migration to a different package with its own option set, and the README's pointer to HTML Minifier Next is the starting point. Budget for re-validating your option configuration against real pages, because the flags you rely on may not carry over with identical semantics.

The licence is MIT, which is permissive and imposes no source-disclosure obligation on your own code. That is the whole of what can be said here; whether MIT fits your organisation's policy is a question for whoever handles that policy, not something this article can settle.

One practical note on version pinning: the repository's default branch is gh-pages, which serves the project homepage and hosted test suite. Do not read activity on that branch as development of the minifier.

## Conclusion

Adopt kangax/html-minifier only if you already depend on it and cannot change the pipeline, and treat the README's own pointer to HTML Minifier Next as the migration target. Do not adopt it for a new project, and do not assume the published npm package reflects the repository's 2026-03-26 push: v4.0.0 shipped in 2019. Before deciding, run the CLI against one real page with the exact option set you intend to use and diff the output, because most options are disabled by default and the defaults are what you will actually get.

## FAQ

### What is an HTML minifier?

It is a tool that removes characters from an HTML document that a parser does not need, such as comments and redundant whitespace, without changing the document tree. kangax/html-minifier does this in JavaScript and exposes each transformation as an option.

### How can I minify my HTML code online?

The project homepage at kangax.github.io/html-minifier is the online entry point, and the README also links a hosted test suite where you can see what options do to specific constructs. For repeatable builds the README documents the CLI and a sample config file instead.

### What is the best HTML minifier?

The README's own comparison table puts kangax/html-minifier ahead of minimize, the Will Peavy minifier and htmlcompressor.com on the sites it lists, but that table is the project's own documentation. The same README tells readers to use HTML Minifier Next for new features and critical security fixes.

### Is there an alternative to kangax/html-minifier?

Yes, and the README names it first: HTML Minifier Next (HMN) from j9t, described there as an up-to-date version with new features and critical security fixes. The README also links Grunt, Gulp, Koa, Express and Ruby wrappers around the same minifier.

## Sources

- [kangax/html-minifier on GitHub](https://github.com/kangax/html-minifier)
- [License: MIT](https://github.com/kangax/html-minifier/blob/gh-pages/LICENSE)
- [Project website](http://kangax.github.io/html-minifier/)
- [README](https://github.com/kangax/html-minifier/blob/gh-pages/README.md)
- [Releases](https://github.com/kangax/html-minifier/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/kangax-html-minifier