htmlnano

3.2.1 verified Fri May 01 auth: no javascript

Modular HTML minifier built on PostHTML, version 3.2.1 (stable). Released occasionally, with recent versions focusing on TypeScript migration, performance improvements, and edge case fixes. Key differentiators: modular architecture allowing selective enabling/disabling of minification modules, presets (safe, max), and extensive configuration options. Compared to html-minifier-terser or minify-html, htmlnano offers deeper integration with PostHTML ecosystem and supports advanced features like CSS/JS minification via optional peer dependencies (cssnano, terser). Includes CLI tool and TypeScript types.

Common errors

error Error: Cannot find module 'cssnano' ↓

cause Optional peer dependency cssnano is not installed.

fix

Install cssnano: npm install cssnano --save-dev

error TypeError: htmlnano.process is not a function ↓

cause Using require() on ESM-only module, or importing incorrectly.

fix

Use import htmlnano from 'htmlnano' instead of require.

error Error: Preset must be one of: safe, max ↓

cause Invalid preset name passed to process function.

fix

Use 'safe' or 'max' (string) as preset, or omit to use default.

Warnings

breaking SVGO upgraded to v4 in htmlnano v3.0.0, which includes breaking changes. See https://svgo.dev/docs/migrations/migration-from-v3-to-v4/ ↓

fix Review SVGO v4 migration guide; adjust SVG optimization options if needed.

deprecated Callback API removed in v2.0.0. Use Promise-based API. ↓

fix Replace callback with async/await or .then().

gotcha CommonJS import broken in v2.1.4 and v2.1.5, later fixed in v2.1.6? Check CHANGELOG. ↓

fix Use ESM import or upgrade to v2.1.6+.

gotcha TypeScript types removed peer dependency type imports in v3.2.1 to avoid requiring peer dep types to be installed, but users may need to install types separately for optional modules. ↓

fix Install types for optional peer dependencies (e.g., @types/cssnano) if needed.

gotcha removeUnusedCss module now uses purgeCSS as default since v3.2.0, which requires purgecss peer dependency. ↓

fix Install purgecss as peer dependency if using removeUnusedCss.

Install

npm install htmlnano

yarn add htmlnano

pnpm add htmlnano

Imports

default export
wrong
```
const htmlnano = require('htmlnano')
```
correct
```
import htmlnano from 'htmlnano'
```
htmlnano v3 is ESM-only. CommonJS require() may work in some environments but is not officially supported.

process

wrong

htmlnano.process(html, options, preset, postHtmlOptions, callback)

correct

import htmlnano from 'htmlnano'; const result = await htmlnano.process(html, options)

process returns a Promise. Callback style is not supported.

Preset type
wrong
```
import { Preset } from 'htmlnano'
```
correct
```
import type { Preset } from 'htmlnano'
```
Preset is a type export; use 'import type' for TypeScript.

Quickstart

Basic usage of htmlnano to minify HTML with whitespace collapse option.

import htmlnano from 'htmlnano';

const html = '<div>  <p>Hello</p>  </div>';
const options = {
  collapseWhitespace: 'conservative'
};

try {
  const result = await htmlnano.process(html, options);
  console.log(result.html); // '<div><p>Hello</p></div>'
} catch (err) {
  console.error(err);
}