or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-html-minifier

Highly configurable, well-tested, JavaScript-based HTML minifier with extensive optimization options

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/html-minifier@4.0.x

To install, run

npx @tessl/cli install tessl/npm-html-minifier@4.0.0

index.mddocs/

HTML Minifier

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.

Package Information

  • Package Name: html-minifier
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install html-minifier

Core Imports

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

For ES6 modules:

import { minify } from "html-minifier";

Basic Usage

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

const html = `
<!DOCTYPE html>
<html>
  <head>
    <title>My Page</title>
    <style>
      body { margin: 0; }
    </style>
  </head>
  <body>
    <h1>Hello World</h1>
    <script>
      console.log("Hello");
    </script>
  </body>
</html>
`;

// Basic minification
const minified = minify(html, {
  collapseWhitespace: true,
  removeComments: true,
  minifyCSS: true,
  minifyJS: true
});

console.log(minified);

Architecture

HTML Minifier is built around several key components:

  • Core Minifier: The main minify() function that processes HTML through a parsing and optimization pipeline
  • HTML Parser: Custom HTML parser that builds a DOM-like tree structure for manipulation
  • Optimization Engine: Configurable rules for whitespace collapse, tag removal, and attribute optimization
  • Sub-processors: Integration with external minifiers for CSS (clean-css) and JavaScript (uglify-js)
  • CLI Interface: Command-line tool with comprehensive option support and batch processing capabilities

Capabilities

HTML Minification

Primary HTML minification function that reduces file size through configurable optimization rules.

/**
 * Minifies HTML content with configurable options
 * @param {string} value - HTML string to minify
 * @param {MinificationOptions} options - Configuration options (optional)
 * @returns {string} Minified HTML string
 */
function minify(value, options);

interface MinificationOptions {
  // Whitespace and formatting
  collapseWhitespace?: boolean;
  collapseInlineTagWhitespace?: boolean;
  conservativeCollapse?: boolean;
  preserveLineBreaks?: boolean;
  trimCustomFragments?: boolean;
  maxLineLength?: number;
  
  // Comments
  removeComments?: boolean;
  processConditionalComments?: boolean;
  ignoreCustomComments?: RegExp[];
  
  // Attributes
  removeAttributeQuotes?: boolean;
  removeEmptyAttributes?: boolean;
  removeRedundantAttributes?: boolean;
  collapseBooleanAttributes?: boolean;
  caseSensitive?: boolean;
  sortAttributes?: boolean;
  preventAttributesEscaping?: boolean;
  
  // Tags and elements
  removeOptionalTags?: boolean;
  removeEmptyElements?: boolean;
  removeTagWhitespace?: boolean;
  includeAutoGeneratedTags?: boolean;
  keepClosingSlash?: boolean;
  
  // Script and style processing
  minifyJS?: boolean | object | ((text: string, inline: boolean) => string);
  minifyCSS?: boolean | object | ((text: string, type: string) => string);
  minifyURLs?: boolean | string | object | ((text: string) => string);
  removeScriptTypeAttributes?: boolean;
  removeStyleLinkTypeAttributes?: boolean;
  processScripts?: string[];
  
  // HTML5 and parsing
  html5?: boolean;
  continueOnParseError?: boolean;
  decodeEntities?: boolean;
  useShortDoctype?: boolean;
  
  // Custom patterns
  customAttrAssign?: RegExp[];
  customAttrSurround?: RegExp[];
  customAttrCollapse?: RegExp;
  customEventAttributes?: RegExp[];
  ignoreCustomFragments?: RegExp[];
  
  // CSS class handling
  sortClassName?: boolean | ((value: string) => string);
  
  // Quote handling
  quoteCharacter?: string;
  
  // Logging
  log?: (message: string) => void;
}

Default Values:

// Default options applied by html-minifier
{
  html5: true,
  ignoreCustomComments: [/^!/],
  ignoreCustomFragments: [/<%[\s\S]*?%>/, /<\?[\s\S]*?\?>/],
  includeAutoGeneratedTags: true,
  log: function() {} // No-op logging function
}

Usage Examples:

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

// Aggressive minification
const result = minify(html, {
  collapseWhitespace: true,
  removeComments: true,
  removeRedundantAttributes: true,
  removeEmptyAttributes: true,
  removeOptionalTags: true,
  minifyCSS: true,
  minifyJS: true,
  minifyURLs: true
});

// Conservative minification with custom options
const conservativeResult = minify(html, {
  collapseWhitespace: true,
  conservativeCollapse: true, // Always keep at least one space
  removeComments: true,
  ignoreCustomComments: [/^!/, /^\s*#/], // Keep certain comments
  minifyCSS: {
    level: 1 // Basic CSS optimization only
  },
  minifyJS: {
    compress: false, // No JavaScript compression
    mangle: false
  }
});

// Custom validation function for empty attributes
const customResult = minify(html, {
  removeEmptyAttributes: (attrName, tag) => {
    // Only remove empty class and id attributes
    return attrName === 'class' || attrName === 'id';
  }
});

Command Line Interface

Comprehensive CLI for HTML minification with file and directory processing.

# Basic usage
html-minifier input.html

# With options
html-minifier --collapse-whitespace --remove-comments input.html -o output.html

# Process directory
html-minifier --input-dir src --output-dir dist --file-ext html

# Using configuration file
html-minifier -c minify.json input.html

CLI Options:

Core Options:

  • -c, --config-file <file>: Use configuration file (JSON or JS module)
  • -o, --output <file>: Specify output file
  • --input-dir <dir>: Input directory for batch processing
  • --output-dir <dir>: Output directory for batch processing
  • --file-ext <ext>: Extension for files processed in batch mode

Whitespace and Formatting:

  • --collapse-whitespace: Collapse white space that contributes to text nodes
  • --collapse-inline-tag-whitespace: Collapse white space around inline tag whitespace
  • --conservative-collapse: Always leave one space when collapsing whitespace
  • --preserve-line-breaks: Preserve line breaks in text content
  • --trim-custom-fragments: Trim white space around ignoreCustomFragments
  • --max-line-length <n>: Maximum line length

Comments:

  • --remove-comments: Strip HTML comments
  • --process-conditional-comments: Process contents of conditional comments through minifier
  • --ignore-custom-comments <patterns>: Array of regex patterns for comments to preserve

Attributes:

  • --remove-attribute-quotes: Remove quotes around attributes when possible
  • --remove-empty-attributes: Remove all attributes with whitespace-only values
  • --remove-redundant-attributes: Remove attributes when value matches default
  • --collapse-boolean-attributes: Omit attribute values from boolean attributes
  • --case-sensitive: Treat attributes in case sensitive manner
  • --sort-attributes: Sort attributes by frequency
  • --prevent-attributes-escaping: Prevents the escaping of the values of attributes

Tags and Elements:

  • --remove-optional-tags: Remove unrequired tags
  • --remove-empty-elements: Remove all elements with empty contents
  • --remove-tag-whitespace: Remove space between attributes whenever possible
  • --include-auto-generated-tags: Insert tags generated by HTML parser
  • --keep-closing-slash: Keep the trailing slash on singleton elements

Script and Style Processing:

  • --minify-css [value]: Minify CSS in style elements and attributes
  • --minify-js [value]: Minify JavaScript in script elements and attributes
  • --minify-urls [value]: Minify URLs in various attributes
  • --remove-script-type-attributes: Remove type="text/javascript" from script tags
  • --remove-style-link-type-attributes: Remove type="text/css" from style and link tags
  • --process-scripts <types>: Array of script types to process

HTML5 and Parsing:

  • --html5: Parse input according to HTML5 specifications
  • --no-html5: Disable HTML5 mode
  • --continue-on-parse-error: Continue processing when parse errors are encountered
  • --decode-entities: Use direct Unicode characters whenever possible
  • --use-short-doctype: Replaces the doctype with the short (HTML5) doctype

Custom Patterns:

  • --custom-attr-assign <patterns>: Arrays of regex patterns for custom attribute assignment expressions
  • --custom-attr-surround <patterns>: Arrays of regex patterns for custom attribute wrapping expressions
  • --custom-attr-collapse <pattern>: Regex pattern for custom attribute to strip newlines from
  • --custom-event-attributes <patterns>: Arrays of regex patterns for custom event attributes
  • --ignore-custom-fragments <patterns>: Array of regex patterns for fragments to preserve

Other Options:

  • --sort-class-name: Sort style classes by frequency
  • --quote-character <char>: Quote character to use for attributes

HTML Parser Module

Advanced HTML parsing functionality for direct parser access and DOM conversion.

const { HTMLParser, HTMLtoXML, HTMLtoDOM } = require("html-minifier/src/htmlparser");

/**
 * Core HTML parser class for custom parsing scenarios
 * @param {string} html - HTML content to parse
 * @param {object} handler - Handler object with parsing callbacks
 */
function HTMLParser(html, handler);

/**
 * Convert HTML to XML format
 * @param {string} html - HTML content to convert
 * @returns {string} XML formatted output
 */
function HTMLtoXML(html);

/**
 * Convert HTML to DOM structure
 * @param {string} html - HTML content to convert
 * @param {Document} doc - Document object for DOM creation
 * @returns {DocumentFragment} DOM fragment containing parsed HTML
 */
function HTMLtoDOM(html, doc);

Usage Examples:

const { HTMLParser, HTMLtoXML } = require("html-minifier/src/htmlparser");

// Custom parsing with handler
const handler = {
  start: (tag, attrs, unary) => console.log('Start tag:', tag),
  end: (tag) => console.log('End tag:', tag),
  chars: (text) => console.log('Text:', text),
  comment: (text) => console.log('Comment:', text)
};

HTMLParser('<div>Hello <b>world</b></div>', handler);

// Convert HTML to XML
const xml = HTMLtoXML('<div class="test">Content</div>');
console.log(xml); // Output: <div class="test">Content</div>

Utility Functions

Low-level utility functions for map creation and string processing.

const { createMap, createMapFromString } = require("html-minifier/src/utils");

/**
 * Create a lookup map from array of values
 * @param {string[]} values - Array of string values for map keys
 * @param {boolean} ignoreCase - Whether to ignore case for lookups
 * @returns {function} Lookup function that returns boolean for key existence
 */
function createMap(values, ignoreCase);

/**
 * Create a lookup map from comma-separated string
 * @param {string} values - Comma-separated string of values
 * @param {boolean} ignoreCase - Whether to ignore case for lookups
 * @returns {function} Lookup function that returns boolean for key existence
 */
function createMapFromString(values, ignoreCase);

Usage Examples:

const { createMap, createMapFromString } = require("html-minifier/src/utils");

// Create map from array
const tagMap = createMap(['div', 'span', 'p'], false);
console.log(tagMap('div')); // true
console.log(tagMap('section')); // false

// Create map from string
const attrMap = createMapFromString('class,id,style', false);
console.log(attrMap('class')); // true
console.log(attrMap('data-test')); // false

// Case-insensitive map
const caseInsensitiveMap = createMapFromString('DIV,SPAN', true);
console.log(caseInsensitiveMap('div')); // true
console.log(caseInsensitiveMap('SPAN')); // true

Types

interface Attribute {
  name: string;
  value: string;
  quote: string;
  customAssign?: string;
  customOpen?: string;
  customClose?: string;
}

interface ProcessingOptions {
  name: (name: string) => string;
  canCollapseWhitespace: (tag: string, attrs?: Attribute[]) => boolean;
  canTrimWhitespace: (tag: string, attrs?: Attribute[]) => boolean;
  log: (message: string) => void;
  minifyCSS: (text: string, type?: string) => string;
  minifyJS: (text: string, inline?: boolean) => string;
  minifyURLs: (text: string) => string;
}

interface MinificationResult {
  // Minified HTML string returned directly from minify()
  toString(): string;
}

Error Handling

HTML Minifier throws descriptive errors for various failure conditions:

try {
  const result = minify(invalidHtml, options);
} catch (error) {
  console.error("Minification failed:", error.message);
  // Common errors:
  // - Parse errors for malformed HTML
  // - Configuration errors for invalid options
  // - Processing errors from CSS/JS minifiers
}

Error Prevention:

// Handle parse errors gracefully
const result = minify(html, {
  continueOnParseError: true, // Don't abort on parse errors
  log: (message) => console.warn("Warning:", message) // Log warnings
});

// Validate input before processing
if (typeof html !== 'string' || html.trim().length === 0) {
  throw new Error("Input must be a non-empty string");
}

Performance Considerations

  • Built-in timing: The minifier logs processing time automatically
  • Memory usage: Large files may require significant memory during parsing
  • CPU intensive: Complex option combinations increase processing time
  • Streaming: Not supported - entire content must be in memory
// Performance monitoring
const startTime = Date.now();
const result = minify(largeHtml, options);
console.log(`Processed in ${Date.now() - startTime}ms`);

// Memory-efficient processing for large files
const fs = require('fs');
const html = fs.readFileSync('large-file.html', 'utf8');
const minified = minify(html, { 
  maxLineLength: 1000 // Split long lines to manage memory
});

Special Features

SVG Support

SVG elements are automatically detected and processed with case-sensitivity preserved:

const svgHtml = '<svg viewBox="0 0 100 100"><circle cx="50" cy="50" r="40"/></svg>';
const result = minify(svgHtml, {
  caseSensitive: false // Will be automatically enabled for SVG content
});

Conditional Comments

Internet Explorer conditional comments receive special handling:

const ieHtml = '<!--[if IE]><p>You are using Internet Explorer</p><![endif]-->';
const result = minify(ieHtml, {
  processConditionalComments: true // Process content inside conditional comments
});

Custom Fragments

Preserve template syntax and custom markup:

const templateHtml = '<div><?php echo $content; ?></div>{{ angular.expression }}';
const result = minify(templateHtml, {
  ignoreCustomFragments: [
    /\<\?php[\s\S]*?\?\>/,  // PHP tags
    /\{\{[\s\S]*?\}\}/      // Angular expressions
  ]
});

Ignored Sections

Use special comments to preserve specific markup sections:

<!-- htmlmin:ignore -->
<pre>
  This content will be preserved exactly
  including    all    whitespace
</pre>
<!-- htmlmin:ignore -->