html-crush

Minifies HTML/CSS: valid or broken, pure or mixed with other languages

Online web app: htmlcrush.com

Table of Contents

• Install
• Usage
• TLDR;
• Features
• API - Input
• API - Output
• Competition
• Non-deterministic unit tests
• Contributing
• Licence

Install

npm i html-crush

then,

// import using CommonJS require():
const { crush, defaults, version } = require("html-crush");
 
// or import as an ES Module, using "import":
import { crush, defaults, version } from "html-crush";

Here's what you'll get:

⬆ back to top

Usage

const { crush } = require("html-crush");
const res = crush(
  `  <a>
     <b>
   c </b>
   </a>
     <a>
     <b>
   c </b>
   </a>
     <a>
     <b>
   c </b>
   </a>`,
  { removeLineBreaks: true, lineLengthLimit: 8 }
).result;
console.log("res:\n" + JSON.stringify(res, null, 4));
// => "res:
// <a><b> c
// </b></a>
// <a><b> c
// </b></a>
// <a><b> c
// </b></a>
// "

⬆ back to top

TLDR;

Let's minify any input (preferably but not necessarily HTML) without parsing, and do it according to how HTML interprets the whitespace.

We built this minifier so that we were able to minify email templates containing Nunjucks template literals, for example, {% if order.price < 50 %} (notice the bracket). Other tools on the market will fail upon first encounter of non-HTML code.

⬆ back to top

Features

This program:

• Does not parse the input — input can be (X)HTML or whatever or mixed with whatever
• Equally, the input can be with HTML errors, broken HTML, incomplete HTML or not-quite-HTML or whatever
• Mailchimp, Responsys, Exact Target, Campaign Monitor tags in your HTML - all fine - it will minify it

In short, we prioritise the support of broken or mixed-HTML support over both:

1. minification amount (Kangax html-minifier will compress more);
2. speed

The price we pay is, we are not able to detect an invalid HTML/CSS/JS.

As a side priority, this application also takes into consideration human-friendliness:

1. Its API (this npm library) reports progress and its GUI front-end https://htmlcrush.com utilises it to allow a responsive UI
2. We deliberately keep options count under 7
3. GUI also considers white and dark interfaces, use of modern toggle switches, CSS hovers to react to any interaction
4. API (this library) considers giving all possible JavaScript use choices: CommonJS transpiled to ES5, modern untranspiled ES Modules code in ES6, and UMD transpiled to ES5 with all dependencies baked-in, all published to npm and accessible via unpkg CDN
5. Developer friendliness - source is fully set up with console.logs which report the line numbers and all actions as they happen. Production builds (dist/) strip all logging, of course. This means it's easy to come back later or the first time and debug the code

⬆ back to top

API - Input

This library exports a plain object where main function is under a key "crush". That's why you consume it like this:

import { crush, defaults, version } from "html-crush";

Once you get the function, crush, it's API is the following:

crush(str, [opts]) — in other words, two arguments:

1. first argument — string,
2. optional (marked with square brackets above) second argument — options — a plain object

If supplied input arguments are of any other types, an error will be thrown.

⬆ back to top

API - Output

The function exported under key crush will return a plain object where you'll find log data, result string and corresponding string ranges of all actions performed:

⬆ back to top

Optional Options Object

Here it is, in one place, in case you want to copy-paste it somewhere:

{
  lineLengthLimit: 500,
  removeIndentations: true,
  removeLineBreaks: false,
  reportProgressFunc: null,
  breakToTheLeftOf: [
    "</td",
    "<html",
    "<head",
    "<meta",
    "<table",
    "<script",
    "</script",
    "<!DOCTYPE",
    "<style",
    "</style",
    "<title",
    "<body",
    "@media",
    "</html",
    "</body",
    "<!--[if",
    "<!--<![endif"
  ]
}

⬆ back to top

opts.reportProgressFunc

This feature is used in a web worker setup. Basically, you pass the web worker the input (source, options) and it passes you one or more messages back. That can be one message, final result, but it can equally be many messages, for example, a sequence of natural numbers, each meaning progress percentage done so far, AND THEN, finally, full result.

This latter case is exactly what is happening on our front-end GUI, https://emailcrush.com

If you set the optional options object's key's reportProgressFunc value to anything else than a function, an error will be thrown. If you set it to a function, that function will be fed a natural number string, meaning percentage done so far, from 1 to 100.

Now, it's up to you how to distinguish "in progress" results and the final result. I use a random string, which is unlikely to happen in the input and I append that secret random string in front of the percentage being passed. Then, front-end checks did result that came through have a secret random string in front or not. If so, it's progress. If not, it's a final result.

Competition

This library has its strengths and weaknesses.

STRENGTHS:

• We accept any source: broken HTML, HTML mixed whatever programming language, no HTML at all, incomplete HTML and so on, because we process it as a string, we don't parse it
• We're faster than parsing libraries because there's a single loop over the input (as string) and the job's done

WEAKNESSES:

• More prone to bugs compared to parsing libraries.
• This library is newer, so less battle-tested and less-famous has fewer maintainers.

IN GENERAL,

• When parsing libraries break, they'll cause errors and won't give you result at all.
• Non-parsing libraries will never break and will always give you a result, only in failure cases it will be erroneous.

also,

• With parsing libraries, you worry about how to fix the errors in the code to please the parser.
• With non-parsing libraries, you worry, is the result not messed up (because the tool won't tell if things went wrong and it's up to you to judge the result).

In general, when you want to minify a mixed source code like HTML template which contains ESP templating code (or other back-end code), you've pretty much got no choice: either this library or nothing. Web development-oriented libraries are all parsing.

⬆ back to top

Non-deterministic unit tests

This library has usual unit tests written for ava, with coverage tracked by nyc.

Yawn.

We also have non-deterministic unit tests, where the input is random.

The idea is, even if we generate the random input and apply random settings, the result with all whitespace characters wiped should be equal to the original untouched random input with all whitespace characters wiped. In other words, we ensure that no non-whitespace characters were affected by this application. Which is true! This application, at least so far, is not meant to delete any non-whitespace characters and under no settings combination.

Personally, I think this is cool, and I haven't seen it anywhere else.

Here's how to fire it up:

ava test_alt/nondeterministic.js -- --time=3s

Call the file nondeterministic.js located in folder test_alt in ava, pass the duration in seconds you want to generate and run tests. More time, more random tests. Just number, for example -- --time=3 means 3 milliseconds. "s" appended means seconds, for example, -- --time=3s. Three minutes would be -- --time=3m.

⬆ back to top

Contributing

• If you see an error, raise an issue.
• If you want a new feature but can't code it up yourself, also raise an issue. Let's discuss it.
• If you tried to use this package, but something didn't work out, also raise an issue. We'll try to help.
• If you want to contribute some code, fork the monorepo via GitLab, then write code, then file a pull request on GitLab. We'll merge it in and release.

In monorepo, npm libraries are located in packages/ folder. Inside, the source code is located either in src/ folder (normal npm library) or in the root, cli.js (if it's a command line application).

The npm script "dev", the "dev": "rollup -c --dev --silent" builds the development version retaining all console.logs with row numbers. It's handy to have js-row-num-cli installed globally so you can automatically update the row numbers on all console.logs.

⬆ back to top

Licence

MIT License

Copyright (c) 2015-2019 Roy Revelt and other contributors