{"id":11046,"library":"html-minifier","title":"HTMLMinifier","description":"HTMLMinifier is a highly configurable and well-tested JavaScript-based tool designed for aggressive HTML minification. The current stable version is 4.0.0. While minor bug fixes and dependency upgrades are released periodically, major version updates, like the transition from v3 to v4, occur less frequently. Its core functionality involves parsing HTML into a tree structure, applying various optimization rules, and then outputting a compacted HTML string. A key differentiator highlighted in its documentation is its effectiveness in reducing file sizes compared to several alternative solutions, making it suitable for performance optimization in web projects. It provides extensive options to control minification, including collapsing whitespace, removing comments, minifying inline CSS and JavaScript, and handling various HTML tag-specific optimizations.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/kangax/html-minifier","tags":["javascript","cli","compress","compressor","css","html","htmlmin","min"],"install":[{"cmd":"npm install html-minifier","lang":"bash","label":"npm"},{"cmd":"yarn add html-minifier","lang":"bash","label":"yarn"},{"cmd":"pnpm add html-minifier","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary export is a named 'minify' function, not a default export.","wrong":"import minify from 'html-minifier';","symbol":"minify","correct":"import { minify } from 'html-minifier';"},{"note":"CommonJS named import for Node.js environments. This is the most common usage pattern for older Node.js versions.","symbol":"minify","correct":"const { minify } = require('html-minifier');"},{"note":"Direct assignment from the `minify` property of the module export. The module itself is an object with a `minify` method.","wrong":"const htmlMinifier = require('html-minifier'); htmlMinifier();","symbol":"minify","correct":"const minify = require('html-minifier').minify;"}],"quickstart":{"code":"const { minify } = require('html-minifier');\n\nconst html = `\n<!doctype html>\n<html lang=\"en\">\n<head>\n    <meta charset=\"utf-8\">\n    <title>Hello World</title>\n    <!-- This is a comment -->\n    <style>\n        body { font-family: sans-serif; color: #333; /* some comment */ }\n    </style>\n</head>\n<body>\n    <h1>  Welcome to my Page!  </h1>\n    <p>This is a paragraph with   extra    spaces.</p>\n    <script>\n        // Inline JavaScript\n        function greet() {\n            console.log(\"Hello from HTMLMinifier!\");\n        }\n        greet();\n    </script>\n</body>\n</html>\n`;\n\nconst minifiedHtml = minify(html, {\n  removeComments: true,\n  collapseWhitespace: true,\n  collapseBooleanAttributes: true,\n  removeEmptyAttributes: true,\n  removeOptionalTags: true,\n  minifyJS: true,\n  minifyCSS: true,\n  useShortDoctype: true,\n  sortAttributes: true,\n  sortClassName: true,\n  decodeEntities: true,\n});\n\nconsole.log(minifiedHtml);\n/* Expected output:\n<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><title>Hello World</title><style>body{font-family:sans-serif;color:#333}</style></head><body><h1>Welcome to my Page!</h1><p>This is a paragraph with extra spaces.</p><script>function greet(){console.log(\"Hello from HTMLMinifier!\")}greet()</script></body></html>\n*/","lang":"javascript","description":"This quickstart demonstrates how to programmatically minify an HTML string using a comprehensive set of common options for maximum compression, showing before and after output."},"warnings":[{"fix":"Upgrade your Node.js environment to version 6 or higher, or pin `html-minifier` to a version lower than 4.0.0 if unable to upgrade Node.js.","message":"Version 4.0.0 of `html-minifier` dropped support for Node.js versions older than 6. Projects running on Node.js 0.x or 4.x will encounter errors.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Thoroughly review the extensive list of available options in the documentation and enable them based on your project's needs. A good starting point is often `collapseWhitespace`, `removeComments`, `minifyJS`, and `minifyCSS`.","message":"By default, almost all minification options are disabled. Users must explicitly enable desired minification features (e.g., `collapseWhitespace`, `removeComments`) to achieve any compression. Unexpectedly large output is often due to not configuring options.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure the input HTML is well-formed and complete before passing it to `html-minifier`. For templating engines that output fragments, consider minifying the full, rendered HTML page.","message":"`html-minifier` cannot reliably process invalid or partial HTML markup. It parses the input into a tree structure, and malformed input can lead to unexpected or incorrect output, as it attempts to interpret it as a complete, valid tree.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For projects requiring ES6+ JavaScript minification, configure a custom `minifyJS` function with a modern minifier like Terser, or consider using `html-minifier-terser` which bundles Terser directly. Version 4.x updates its dependencies, but this note is particularly relevant for older versions.","message":"The default JavaScript minification library, UglifyJS, used by `html-minifier` for `minifyJS`, is not actively maintained and does not support modern JavaScript syntax (ES6+). This can lead to issues with contemporary JavaScript code.","severity":"deprecated","affected_versions":"<4.0.0"},{"fix":"Consider migrating to `html-minifier-next` for ongoing development, as it addresses many limitations and provides a more up-to-date solution for HTML minification.","message":"There is a newer, actively maintained alternative called `html-minifier-next` (and `html-minifier-terser`) that offers improved features, dependency updates, and better support for modern web standards and Node.js versions.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"The module exports an object. You need to destructure or access the `minify` function: `const { minify } = require('html-minifier');` or `const minify = require('html-minifier').minify;`.","cause":"Attempting to call the `html-minifier` module export directly as a function, rather than accessing its `minify` method.","error":"TypeError: htmlMinifier is not a function"},{"fix":"Upgrade your Node.js installation to version 6 or newer. Alternatively, if upgrading Node.js is not possible, downgrade `html-minifier` to a version compatible with your current Node.js setup (e.g., `npm install html-minifier@3` for Node.js < 6).","cause":"Running `html-minifier` version 4.0.0 or higher on an unsupported Node.js environment.","error":"Error: The 'html-minifier' package requires Node.js version 6 or higher. You are running Node.js version 4.x.x."},{"fix":"Provide an options object to the `minify` function with desired features enabled, such as `collapseWhitespace: true`, `removeComments: true`, `minifyJS: true`, `minifyCSS: true`, etc.","cause":"Most minification options are disabled by default and must be explicitly enabled.","error":"Minified HTML output is not significantly smaller or comments/whitespace are still present."},{"fix":"For JavaScript, consider using a custom `minifyJS` function with a modern minifier like Terser that supports ES6+. For CSS, ensure the inline CSS is valid. If the issue persists, disable inline minification for the problematic section or entire document.","cause":"The default inline JavaScript (UglifyJS) or CSS (Clean-CSS) minifiers do not support modern syntax (e.g., ES6+ JavaScript) or encounter malformed input.","error":"SyntaxError: Invalid or unexpected token in inline JavaScript/CSS during minification."}],"ecosystem":"npm"}