tessl/npm-html-minifier
Highly configurable, well-tested, JavaScript-based HTML minifier with extensive optimization options
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-html-minifier@4.0.00
# HTML Minifier
1
2
HTML Minifier is a highly configurable, well-tested JavaScript-based HTML minifier that reduces HTML file size by removing unnecessary whitespace, comments, and attributes while preserving functionality. It offers extensive configuration options and supports both programmatic use through Node.js APIs and command-line usage.
3
4
## Package Information
5
6
- **Package Name**: html-minifier
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install html-minifier`
10
11
## Core Imports
12
13
```javascript
14
const { minify } = require("html-minifier");
15
```
16
17
For ES6 modules:
18
19
```javascript
20
import { minify } from "html-minifier";
21
```
22
23
## Basic Usage
24
25
```javascript
26
const { minify } = require("html-minifier");
27
28
const html = `
29
<!DOCTYPE html>
30
<html>
31
<head>
32
<title>My Page</title>
33
<style>
34
body { margin: 0; }
35
</style>
36
</head>
37
<body>
38
<h1>Hello World</h1>
39
<script>
40
console.log("Hello");
41
</script>
42
</body>
43
</html>
44
`;
45
46
// Basic minification
47
const minified = minify(html, {
48
collapseWhitespace: true,
49
removeComments: true,
50
minifyCSS: true,
51
minifyJS: true
52
});
53
54
console.log(minified);
55
```
56
57
## Architecture
58
59
HTML Minifier is built around several key components:
60
61
- **Core Minifier**: The main `minify()` function that processes HTML through a parsing and optimization pipeline
62
- **HTML Parser**: Custom HTML parser that builds a DOM-like tree structure for manipulation
63
- **Optimization Engine**: Configurable rules for whitespace collapse, tag removal, and attribute optimization
64
- **Sub-processors**: Integration with external minifiers for CSS (clean-css) and JavaScript (uglify-js)
65
- **CLI Interface**: Command-line tool with comprehensive option support and batch processing capabilities
66
67
## Capabilities
68
69
### HTML Minification
70
71
Primary HTML minification function that reduces file size through configurable optimization rules.
72
73
```javascript { .api }
74
/**
75
* Minifies HTML content with configurable options
76
* @param {string} value - HTML string to minify
77
* @param {MinificationOptions} options - Configuration options (optional)
78
* @returns {string} Minified HTML string
79
*/
80
function minify(value, options);
81
82
interface MinificationOptions {
83
// Whitespace and formatting
84
collapseWhitespace?: boolean;
85
collapseInlineTagWhitespace?: boolean;
86
conservativeCollapse?: boolean;
87
preserveLineBreaks?: boolean;
88
trimCustomFragments?: boolean;
89
maxLineLength?: number;
90
91
// Comments
92
removeComments?: boolean;
93
processConditionalComments?: boolean;
94
ignoreCustomComments?: RegExp[];
95
96
// Attributes
97
removeAttributeQuotes?: boolean;
98
removeEmptyAttributes?: boolean;
99
removeRedundantAttributes?: boolean;
100
collapseBooleanAttributes?: boolean;
101
caseSensitive?: boolean;
102
sortAttributes?: boolean;
103
preventAttributesEscaping?: boolean;
104
105
// Tags and elements
106
removeOptionalTags?: boolean;
107
removeEmptyElements?: boolean;
108
removeTagWhitespace?: boolean;
109
includeAutoGeneratedTags?: boolean;
110
keepClosingSlash?: boolean;
111
112
// Script and style processing
113
minifyJS?: boolean | object | ((text: string, inline: boolean) => string);
114
minifyCSS?: boolean | object | ((text: string, type: string) => string);
115
minifyURLs?: boolean | string | object | ((text: string) => string);
116
removeScriptTypeAttributes?: boolean;
117
removeStyleLinkTypeAttributes?: boolean;
118
processScripts?: string[];
119
120
// HTML5 and parsing
121
html5?: boolean;
122
continueOnParseError?: boolean;
123
decodeEntities?: boolean;
124
useShortDoctype?: boolean;
125
126
// Custom patterns
127
customAttrAssign?: RegExp[];
128
customAttrSurround?: RegExp[];
129
customAttrCollapse?: RegExp;
130
customEventAttributes?: RegExp[];
131
ignoreCustomFragments?: RegExp[];
132
133
// CSS class handling
134
sortClassName?: boolean | ((value: string) => string);
135
136
// Quote handling
137
quoteCharacter?: string;
138
139
// Logging
140
log?: (message: string) => void;
141
}
142
```
143
144
**Default Values:**
145
146
```javascript
147
// Default options applied by html-minifier
148
{
149
html5: true,
150
ignoreCustomComments: [/^!/],
151
ignoreCustomFragments: [/<%[\s\S]*?%>/, /<\?[\s\S]*?\?>/],
152
includeAutoGeneratedTags: true,
153
log: function() {} // No-op logging function
154
}
155
```
156
157
**Usage Examples:**
158
159
```javascript
160
const { minify } = require("html-minifier");
161
162
// Aggressive minification
163
const result = minify(html, {
164
collapseWhitespace: true,
165
removeComments: true,
166
removeRedundantAttributes: true,
167
removeEmptyAttributes: true,
168
removeOptionalTags: true,
169
minifyCSS: true,
170
minifyJS: true,
171
minifyURLs: true
172
});
173
174
// Conservative minification with custom options
175
const conservativeResult = minify(html, {
176
collapseWhitespace: true,
177
conservativeCollapse: true, // Always keep at least one space
178
removeComments: true,
179
ignoreCustomComments: [/^!/, /^\s*#/], // Keep certain comments
180
minifyCSS: {
181
level: 1 // Basic CSS optimization only
182
},
183
minifyJS: {
184
compress: false, // No JavaScript compression
185
mangle: false
186
}
187
});
188
189
// Custom validation function for empty attributes
190
const customResult = minify(html, {
191
removeEmptyAttributes: (attrName, tag) => {
192
// Only remove empty class and id attributes
193
return attrName === 'class' || attrName === 'id';
194
}
195
});
196
```
197
198
### Command Line Interface
199
200
Comprehensive CLI for HTML minification with file and directory processing.
201
202
```bash { .api }
203
# Basic usage
204
html-minifier input.html
205
206
# With options
207
html-minifier --collapse-whitespace --remove-comments input.html -o output.html
208
209
# Process directory
210
html-minifier --input-dir src --output-dir dist --file-ext html
211
212
# Using configuration file
213
html-minifier -c minify.json input.html
214
```
215
216
**CLI Options:**
217
218
**Core Options:**
219
- `-c, --config-file <file>`: Use configuration file (JSON or JS module)
220
- `-o, --output <file>`: Specify output file
221
- `--input-dir <dir>`: Input directory for batch processing
222
- `--output-dir <dir>`: Output directory for batch processing
223
- `--file-ext <ext>`: Extension for files processed in batch mode
224
225
**Whitespace and Formatting:**
226
- `--collapse-whitespace`: Collapse white space that contributes to text nodes
227
- `--collapse-inline-tag-whitespace`: Collapse white space around inline tag whitespace
228
- `--conservative-collapse`: Always leave one space when collapsing whitespace
229
- `--preserve-line-breaks`: Preserve line breaks in text content
230
- `--trim-custom-fragments`: Trim white space around ignoreCustomFragments
231
- `--max-line-length <n>`: Maximum line length
232
233
**Comments:**
234
- `--remove-comments`: Strip HTML comments
235
- `--process-conditional-comments`: Process contents of conditional comments through minifier
236
- `--ignore-custom-comments <patterns>`: Array of regex patterns for comments to preserve
237
238
**Attributes:**
239
- `--remove-attribute-quotes`: Remove quotes around attributes when possible
240
- `--remove-empty-attributes`: Remove all attributes with whitespace-only values
241
- `--remove-redundant-attributes`: Remove attributes when value matches default
242
- `--collapse-boolean-attributes`: Omit attribute values from boolean attributes
243
- `--case-sensitive`: Treat attributes in case sensitive manner
244
- `--sort-attributes`: Sort attributes by frequency
245
- `--prevent-attributes-escaping`: Prevents the escaping of the values of attributes
246
247
**Tags and Elements:**
248
- `--remove-optional-tags`: Remove unrequired tags
249
- `--remove-empty-elements`: Remove all elements with empty contents
250
- `--remove-tag-whitespace`: Remove space between attributes whenever possible
251
- `--include-auto-generated-tags`: Insert tags generated by HTML parser
252
- `--keep-closing-slash`: Keep the trailing slash on singleton elements
253
254
**Script and Style Processing:**
255
- `--minify-css [value]`: Minify CSS in style elements and attributes
256
- `--minify-js [value]`: Minify JavaScript in script elements and attributes
257
- `--minify-urls [value]`: Minify URLs in various attributes
258
- `--remove-script-type-attributes`: Remove type="text/javascript" from script tags
259
- `--remove-style-link-type-attributes`: Remove type="text/css" from style and link tags
260
- `--process-scripts <types>`: Array of script types to process
261
262
**HTML5 and Parsing:**
263
- `--html5`: Parse input according to HTML5 specifications
264
- `--no-html5`: Disable HTML5 mode
265
- `--continue-on-parse-error`: Continue processing when parse errors are encountered
266
- `--decode-entities`: Use direct Unicode characters whenever possible
267
- `--use-short-doctype`: Replaces the doctype with the short (HTML5) doctype
268
269
**Custom Patterns:**
270
- `--custom-attr-assign <patterns>`: Arrays of regex patterns for custom attribute assignment expressions
271
- `--custom-attr-surround <patterns>`: Arrays of regex patterns for custom attribute wrapping expressions
272
- `--custom-attr-collapse <pattern>`: Regex pattern for custom attribute to strip newlines from
273
- `--custom-event-attributes <patterns>`: Arrays of regex patterns for custom event attributes
274
- `--ignore-custom-fragments <patterns>`: Array of regex patterns for fragments to preserve
275
276
**Other Options:**
277
- `--sort-class-name`: Sort style classes by frequency
278
- `--quote-character <char>`: Quote character to use for attributes
279
280
### HTML Parser Module
281
282
Advanced HTML parsing functionality for direct parser access and DOM conversion.
283
284
```javascript { .api }
285
const { HTMLParser, HTMLtoXML, HTMLtoDOM } = require("html-minifier/src/htmlparser");
286
287
/**
288
* Core HTML parser class for custom parsing scenarios
289
* @param {string} html - HTML content to parse
290
* @param {object} handler - Handler object with parsing callbacks
291
*/
292
function HTMLParser(html, handler);
293
294
/**
295
* Convert HTML to XML format
296
* @param {string} html - HTML content to convert
297
* @returns {string} XML formatted output
298
*/
299
function HTMLtoXML(html);
300
301
/**
302
* Convert HTML to DOM structure
303
* @param {string} html - HTML content to convert
304
* @param {Document} doc - Document object for DOM creation
305
* @returns {DocumentFragment} DOM fragment containing parsed HTML
306
*/
307
function HTMLtoDOM(html, doc);
308
```
309
310
**Usage Examples:**
311
312
```javascript
313
const { HTMLParser, HTMLtoXML } = require("html-minifier/src/htmlparser");
314
315
// Custom parsing with handler
316
const handler = {
317
start: (tag, attrs, unary) => console.log('Start tag:', tag),
318
end: (tag) => console.log('End tag:', tag),
319
chars: (text) => console.log('Text:', text),
320
comment: (text) => console.log('Comment:', text)
321
};
322
323
HTMLParser('<div>Hello <b>world</b></div>', handler);
324
325
// Convert HTML to XML
326
const xml = HTMLtoXML('<div class="test">Content</div>');
327
console.log(xml); // Output: <div class="test">Content</div>
328
```
329
330
### Utility Functions
331
332
Low-level utility functions for map creation and string processing.
333
334
```javascript { .api }
335
const { createMap, createMapFromString } = require("html-minifier/src/utils");
336
337
/**
338
* Create a lookup map from array of values
339
* @param {string[]} values - Array of string values for map keys
340
* @param {boolean} ignoreCase - Whether to ignore case for lookups
341
* @returns {function} Lookup function that returns boolean for key existence
342
*/
343
function createMap(values, ignoreCase);
344
345
/**
346
* Create a lookup map from comma-separated string
347
* @param {string} values - Comma-separated string of values
348
* @param {boolean} ignoreCase - Whether to ignore case for lookups
349
* @returns {function} Lookup function that returns boolean for key existence
350
*/
351
function createMapFromString(values, ignoreCase);
352
```
353
354
**Usage Examples:**
355
356
```javascript
357
const { createMap, createMapFromString } = require("html-minifier/src/utils");
358
359
// Create map from array
360
const tagMap = createMap(['div', 'span', 'p'], false);
361
console.log(tagMap('div')); // true
362
console.log(tagMap('section')); // false
363
364
// Create map from string
365
const attrMap = createMapFromString('class,id,style', false);
366
console.log(attrMap('class')); // true
367
console.log(attrMap('data-test')); // false
368
369
// Case-insensitive map
370
const caseInsensitiveMap = createMapFromString('DIV,SPAN', true);
371
console.log(caseInsensitiveMap('div')); // true
372
console.log(caseInsensitiveMap('SPAN')); // true
373
```
374
375
## Types
376
377
```javascript { .api }
378
interface Attribute {
379
name: string;
380
value: string;
381
quote: string;
382
customAssign?: string;
383
customOpen?: string;
384
customClose?: string;
385
}
386
387
interface ProcessingOptions {
388
name: (name: string) => string;
389
canCollapseWhitespace: (tag: string, attrs?: Attribute[]) => boolean;
390
canTrimWhitespace: (tag: string, attrs?: Attribute[]) => boolean;
391
log: (message: string) => void;
392
minifyCSS: (text: string, type?: string) => string;
393
minifyJS: (text: string, inline?: boolean) => string;
394
minifyURLs: (text: string) => string;
395
}
396
397
interface MinificationResult {
398
// Minified HTML string returned directly from minify()
399
toString(): string;
400
}
401
```
402
403
## Error Handling
404
405
HTML Minifier throws descriptive errors for various failure conditions:
406
407
```javascript
408
try {
409
const result = minify(invalidHtml, options);
410
} catch (error) {
411
console.error("Minification failed:", error.message);
412
// Common errors:
413
// - Parse errors for malformed HTML
414
// - Configuration errors for invalid options
415
// - Processing errors from CSS/JS minifiers
416
}
417
```
418
419
**Error Prevention:**
420
421
```javascript
422
// Handle parse errors gracefully
423
const result = minify(html, {
424
continueOnParseError: true, // Don't abort on parse errors
425
log: (message) => console.warn("Warning:", message) // Log warnings
426
});
427
428
// Validate input before processing
429
if (typeof html !== 'string' || html.trim().length === 0) {
430
throw new Error("Input must be a non-empty string");
431
}
432
```
433
434
## Performance Considerations
435
436
- **Built-in timing**: The minifier logs processing time automatically
437
- **Memory usage**: Large files may require significant memory during parsing
438
- **CPU intensive**: Complex option combinations increase processing time
439
- **Streaming**: Not supported - entire content must be in memory
440
441
```javascript
442
// Performance monitoring
443
const startTime = Date.now();
444
const result = minify(largeHtml, options);
445
console.log(`Processed in ${Date.now() - startTime}ms`);
446
447
// Memory-efficient processing for large files
448
const fs = require('fs');
449
const html = fs.readFileSync('large-file.html', 'utf8');
450
const minified = minify(html, {
451
maxLineLength: 1000 // Split long lines to manage memory
452
});
453
```
454
455
## Special Features
456
457
### SVG Support
458
459
SVG elements are automatically detected and processed with case-sensitivity preserved:
460
461
```javascript
462
const svgHtml = '<svg viewBox="0 0 100 100"><circle cx="50" cy="50" r="40"/></svg>';
463
const result = minify(svgHtml, {
464
caseSensitive: false // Will be automatically enabled for SVG content
465
});
466
```
467
468
### Conditional Comments
469
470
Internet Explorer conditional comments receive special handling:
471
472
```javascript
473
const ieHtml = '<!--[if IE]><p>You are using Internet Explorer</p><![endif]-->';
474
const result = minify(ieHtml, {
475
processConditionalComments: true // Process content inside conditional comments
476
});
477
```
478
479
### Custom Fragments
480
481
Preserve template syntax and custom markup:
482
483
```javascript
484
const templateHtml = '<div><?php echo $content; ?></div>{{ angular.expression }}';
485
const result = minify(templateHtml, {
486
ignoreCustomFragments: [
487
/\<\?php[\s\S]*?\?\>/, // PHP tags
488
/\{\{[\s\S]*?\}\}/ // Angular expressions
489
]
490
});
491
```
492
493
### Ignored Sections
494
495
Use special comments to preserve specific markup sections:
496
497
```html
498
<!-- htmlmin:ignore -->
499
<pre>
500
This content will be preserved exactly
501
including all whitespace
502
</pre>
503
<!-- htmlmin:ignore -->
504
```