html-minifier-next

6.2.0 verified Fri May 01 auth: no javascript

html-minifier-next v6.2.0 is a super-configurable, JavaScript-based HTML minifier that also handles in-document CSS, JavaScript, and SVG minification. It is the actively maintained successor of the now-unmaintained HTML Minifier Terser and original HTML Minifier by kangax. The library is optimized for speed, offers both CLI and Node.js API, supports preset configurations, and ships TypeScript definitions. It requires @swc/core as a peer dependency for JavaScript minification. Released with monthly cadence, it aims to be backwards-compatible with its predecessors while adding new features like zero-config mode and ignore-dir support.

Common errors

error SyntaxError: Unexpected token '?' ↓

cause Using an older Node.js version (<14) that does not support optional chaining.

fix

Upgrade Node.js to >=14.0.0 (recommended >=16.14 for full ESM support).

error Error: Cannot find module '@swc/core' ↓

cause minifyJS option enabled but @swc/core peer dependency is not installed.

fix

Run 'npm install @swc/core' or set 'minifyJS: false'.

error TypeError: html_minifier_next_1.minify is not a function ↓

cause Incorrect import: using default import instead of named import.

fix

Use 'import { minify } from 'html-minifier-next'' instead of 'import minify from ...'.

error Error: Config file 'html-minifier.json' not found ↓

cause Config file path is relative to cwd but file is in a different directory.

fix

Use absolute path or change working directory: --config-file ./config/html-minifier.json

Warnings

breaking All CommonJS require() calls will throw an error. This package is ESM-only. ↓

fix Use import { minify } from 'html-minifier-next' or dynamic import: const { minify } = await import('html-minifier-next').

deprecated Setting minifyJS to true without installing @swc/core will cause the minifier to fall back to a no-op or throw an error depending on version. ↓

fix Install @swc/core as a dependency: npm install @swc/core. Alternatively, provide a custom minifyJS function.

gotcha minify function expects a string input; if you pass a Buffer or other object, it may be coerced to string incorrectly or throw. ↓

fix Always pass a string: const result = minify(String(html), options).

gotcha Configuration file paths are relative to the current working directory, not the file being processed. ↓

fix Use absolute paths or ensure the config file is in the project root when running CLI.

gotcha The default values for options like 'collapseWhitespace' and 'removeComments' are false. If you expect aggressive minification without specifying options, results may be unexpected. ↓

fix Explicitly set desired options. Use preset='comprehensive' via CLI or configure options programmatically.

Install

npm install html-minifier-next

yarn add html-minifier-next

pnpm add html-minifier-next

Imports

minify
wrong
```
const { minify } = require('html-minifier-next')
```
correct
```
import { minify } from 'html-minifier-next'
```
ESM-only since v6; CommonJS require is not supported. Use dynamic import if needed: const { minify } = await import('html-minifier-next').
default (minify)
wrong
```
import minify from 'html-minifier-next'
```
correct
```
import { minify } from 'html-minifier-next'
```
This package only exports named exports; there is no default export. Using default import will result in 'undefined' at runtime.
MinifyOptions type
wrong
```
import { MinifyOptions } from 'html-minifier-next'
```
correct
```
import type { MinifyOptions } from 'html-minifier-next'
```
TypeScript users: MinifyOptions is a type-only export. Use 'import type' to avoid bundling issues in some environments.

Quickstart

Basic usage: minify HTML string with options to collapse whitespace, remove comments, and inline CSS/JS minification.

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

const html = `
<!DOCTYPE html>
<html>
<head>
  <title>Test</title>
</head>
<body>
  <p>Hello World</p>
</body>
</html>`;

const options = {
  collapseWhitespace: true,
  removeComments: true,
  minifyJS: true,
  minifyCSS: true
};

const result = minify(html, options);
console.log(result);
// Output: <!DOCTYPE html><html><head><title>Test</title></head><body><p>Hello World</p></body></html>