HTMLMinifier

Common errors

• TypeError: htmlMinifier is not a function

  cause Attempting to call the `html-minifier` module export directly as a function, rather than accessing its `minify` method.
  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;`.

• Error: The 'html-minifier' package requires Node.js version 6 or higher. You are running Node.js version 4.x.x.

  cause Running `html-minifier` version 4.0.0 or higher on an unsupported Node.js environment.
  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).

• Minified HTML output is not significantly smaller or comments/whitespace are still present.

  cause Most minification options are disabled by default and must be explicitly enabled.
  fix Provide an options object to the `minify` function with desired features enabled, such as `collapseWhitespace: true`, `removeComments: true`, `minifyJS: true`, `minifyCSS: true`, etc.

• SyntaxError: Invalid or unexpected token in inline JavaScript/CSS during minification.

  cause The default inline JavaScript (UglifyJS) or CSS (Clean-CSS) minifiers do not support modern syntax (e.g., ES6+ JavaScript) or encounter malformed input.
  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.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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`.
• gotcha `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.
  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.
• deprecated 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.
  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.
• gotcha 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.
  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.

Install

• npm install html-minifier npm
• yarn add html-minifier yarn
• pnpm add html-minifier pnpm

Imports

• minify
  wrong:

  import minify from 'html-minifier';

  correct:

  import { minify } from 'html-minifier';

  The primary export is a named 'minify' function, not a default export.
• minify

  const { minify } = require('html-minifier');

  CommonJS named import for Node.js environments. This is the most common usage pattern for older Node.js versions.
• minify
  wrong:

  const htmlMinifier = require('html-minifier'); htmlMinifier();

  correct:

  const minify = require('html-minifier').minify;

  Direct assignment from the `minify` property of the module export. The module itself is an object with a `minify` method.

Quickstart

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.

const { minify } = require('html-minifier');

const html = `
<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Hello World</title>
    <!-- This is a comment -->
    <style>
        body { font-family: sans-serif; color: #333; /* some comment */ }
    </style>
</head>
<body>
    <h1>  Welcome to my Page!  </h1>
    <p>This is a paragraph with   extra    spaces.</p>
    <script>
        // Inline JavaScript
        function greet() {
            console.log("Hello from HTMLMinifier!");
        }
        greet();
    </script>
</body>
</html>
`;

const minifiedHtml = minify(html, {
  removeComments: true,
  collapseWhitespace: true,
  collapseBooleanAttributes: true,
  removeEmptyAttributes: true,
  removeOptionalTags: true,
  minifyJS: true,
  minifyCSS: true,
  useShortDoctype: true,
  sortAttributes: true,
  sortClassName: true,
  decodeEntities: true,
});

console.log(minifiedHtml);
/* Expected output:
<!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>
*/