html-crush^6.3.0

Permalink to InstallationInstallation

Permalink to Quick TakeQuick Take

Permalink to ExamplesExamples

• Configure CSS comment removal
• Insert line breaks before selected tokens
• Treat a custom element as inline
• Choose which HTML comments to remove
• Wrap minified HTML at a line-length limit
• Observe progress in a custom interval
• Remove line indentations
• Remove HTML line breaks
• Inspect result metadata and edit ranges

Purpose

html-crush minifies mixed HTML and CSS, with a focus on email templates. It scans the input without parsing it into an abstract syntax tree, so it can work with incomplete markup and templates that contain Nunjucks, JSP, ESP, CDATA, or other embedded languages.

Email HTML needs controls that general web-page minifiers do not always provide. For example, you can preserve Outlook conditional comments and place line breaks before selected tokens to keep generated lines within an email transport limit.

The scanner preserves ordinary quoted attribute values, CSS strings, and the contents of script, pre, code, and textarea elements. HTML element names are matched case-insensitively.

API — crush()

The main function crush() is imported like this:

Pass the HTML source as a string and, optionally, an options object or null:

function crush(str: string, opts?: InputOpts | null): Res;

InputOpts has the following shape. Every property is optional:

interface InputOpts {
  lineLengthLimit?: number;
  removeIndentations?: boolean;
  removeLineBreaks?: boolean;
  removeHTMLComments?: boolean | 0 | 1 | 2;
  removeCSSComments?: boolean;
  reportProgressFunc?: null | false | 0 | ((percentage: number) => void);
  reportProgressFuncFrom?: number;
  reportProgressFuncTo?: number;
  breakToTheLeftOf?: string[] | null | false;
  mindTheInlineTags?: string[];
}

Here are all defaults in one place for copying:

The function returns a plain Res object:

type Range =
  | [from: number, to: number]
  | [from: number, to: number, whatToInsert: string | null | undefined];

interface Res {
  log: {
    timeTakenInMilliseconds: number;
    originalLength: number;
    cleanedLength: number;
    bytesSaved: number;
    percentageReducedOfOriginal: number;
    originalLengthInCodeUnits: number;
    cleanedLengthInCodeUnits: number;
    codeUnitsSaved: number;
    percentageReducedOfOriginalInCodeUnits: number;
    originalLengthInUtf8Bytes: number;
    cleanedLengthInUtf8Bytes: number;
    utf8BytesSaved: number;
    percentageReducedOfOriginalInUtf8Bytes: number;
  };
  applicableOpts: {
    removeHTMLComments: boolean;
    removeCSSComments: boolean;
  };
  ranges: Range[] | null;
  result: string;
}

The result contains only plain objects, arrays, strings, numbers, booleans, and null. It can be serialized as JSON or sent through postMessage().

Size and timing fields

JavaScript string lengths count UTF-16 code units, not bytes. The explicit fields distinguish those lengths from the UTF-8 size that an encoded email would occupy. Percentages are rounded to the nearest integer.

For compatibility, the four legacy size fields keep their existing UTF-16 code-unit meaning. Use the explicit fields in new integrations.

Progress reporting

Use reportProgressFunc when crush() runs in a Web Worker or another UI that needs completion feedback. Inputs of 1,000 code units or fewer do not call the callback. Inputs from 1,001 through 1,999 code units report a midpoint and completion. Longer inputs report incremental values.

Every reported value is an integer within the interval configured by reportProgressFuncFrom and reportProgressFuncTo. Both changed and unchanged inputs finish at the configured ending value. The callback is observational: it does not change the result, ranges, or deterministic statistics.

import { crush } from "html-crush";

const res = crush(source, {
  removeLineBreaks: true,
  reportProgressFunc: (percentage) => {
    postMessage({ type: "progress", percentage });
  },
});

postMessage({ type: "result", res });

API — defaults

You can import defaults:

It's a plain object:

The main function calculates the options to be used by merging the options you passed with these defaults.

API — version

You can import version:

API — types

This package is written in TypeScript and exports these public types:

import type { InputOpts, Opts, Res } from "html-crush";

Permalink to changelogChangelog