How to Minify CSS, JavaScript and HTML Safely

Stylesheets, scripts and pages are written for people: comments explain decisions, indentation shows structure and long names say what a variable is for. A browser needs none of that. Minifying strips the parts only humans use so the file is smaller to download. It is a simple idea that is often oversold, and some minifiers can change behavior when they are careless. This guide explains what minifying does, what it really saves, and how to check the result before it reaches visitors.

What minifying actually does

A minifier rewrites a file into an equivalent one that is shorter. Depending on the language and the tool, that means:

• Removing comments, indentation and line breaks.
• Collapsing runs of spaces and deleting spaces around punctuation that does not need them.
• For JavaScript, optionally shortening the names of local variables and simplifying the code, for example by removing statements that can never run.

There are two kinds of minifier, and the difference matters. A parser-based tool reads the code the way a browser would, so it knows where strings, comments and expressions start and end. The JavaScript Minifier works this way: it uses Terser, the engine many build tools use. A text-based tool applies find-and-replace rules to the raw text. The CSS Minifier and HTML Minifier are of this kind. They are written to protect the risky parts, such as quoted strings, url() contents, preformatted text and the space in a selector like .card :hover, but they do not build a full syntax tree, so check their output instead of assuming it is perfect.

With Compress and Shorten local variable names switched on, a function that adds two numbers through a temporary variable called total can come out as function addNumbers(e,r){return e+r}. Notice what stayed the same: the top-level function name and any object property names are left alone, because other files or HTML attributes may call them. Leave the ES module option off for a classic script that other code calls by name, because module mode allows top-level names to be shortened too.

What you save, and what gzip and Brotli change

The before and after figure is the size of the text files. Visitors usually download a compressed copy, because web servers commonly apply gzip or Brotli to text files such as CSS, JavaScript and HTML. Those algorithms are good at repeated patterns like indentation, so a file that shrinks a lot when minified shrinks much less once both versions are compressed. Minifying still helps, since a minified file usually compresses to a smaller result than the original does, but the gap is narrower than the headline percentage suggests.

To see the real effect, open your browser's developer tools, go to the network panel and compare the transferred size with the resource size of the file. The transferred size is what actually crossed the network.

The JavaScript, JSON, CSS and HTML minifiers all show the size in bytes before and after, with the percentage saved, so you can see the gain for your own file.

Source maps and debugging

Once names and line breaks are gone, an error in the browser console points at line 1, column 48213 of an unreadable file. A source map solves this. It is a separate file that maps positions in the minified code back to the original source, referenced by a comment at the end of the minified file, and browser developer tools read it when they are open. Bundlers and Terser's command-line tools can create source maps. The JavaScript Minifier on this site minifies the code you paste and does not produce one.

Without a source map, keep the original and the minified file together and use a formatter to read the minified one. The JavaScript Formatter, CSS Formatter and HTML Formatter restore indentation and line breaks. They cannot restore comments or the original variable names, which is why the readable source stays your master copy.

Test the minified output

Parser-based minification should not change behavior. Text-based minification has a few predictable weak spots, so treat its output as something to check.

• CSS: comments and the whitespace around braces, colons in declarations, semicolons and commas are removed. The space in a descendant selector such as .card :hover is kept, because dropping it would make .card:hover, which matches a different element. Quoted strings such as content: "a b" and url() contents are left exactly as written, colours and units are never shortened, and /! licence / comments are kept unless you untick the option. The tool does not check that your CSS is valid, so validate it first.
• HTML: a line break becomes a single space, so words on separate lines stay separate. Whitespace next to block tags such as div, p and li is removed, while one space is kept between inline elements like bold and italic text. Comments are removed unless you untick the option, and conditional comments are kept. The contents of pre, textarea and script elements and quoted attribute values are left as written. The remaining risk is a layout that depends on the spaces between inline-block elements, so look at the page, not only the file size.

Whichever tool you use, a short routine catches most problems.

1. Keep the readable source and minify a copy, never the only version.
2. Paste the original and the minified CSS into the CSS Validator and compare the reports. The minified copy should not introduce new errors.
3. Run minified markup through the HTML Validator for unclosed tags and duplicate ids.
4. Load the result on a staging page, open the browser console, and look for errors before you check the layout and click through the main actions.
5. Deploy only after the staged page behaves like the original.

The HTML Minifier leaves the contents of script elements exactly as written. To shrink an inline script, move it into its own file and minify it with the JavaScript Minifier, then let the HTML Minifier handle the markup. What a syntax check can and cannot tell you is covered in what validators catch and what they miss.

Other formats

Data and graphics minify the same way. The JSON Minifier parses the input first, so invalid JSON is reported instead of producing broken output, and whitespace inside string values is preserved. The SVG Minifier removes the XML declaration, comments and formatting whitespace, keeps spacing inside text, title and style elements, and does not rewrite path data.

When not to minify

• The file is already minified. Files with a .min suffix in the name have usually been through the process already, and a second pass saves little.
• Your build already does it. Many build tools minify production output automatically, so check your configuration before adding a manual step.
• The file is tiny. Saving a few dozen bytes rarely justifies another step to maintain.
• You cannot test the result. Text-based minifiers on code you cannot run afterwards are a risk with no visible reward.
• Readability is the point. During development and debugging, work with the readable file and minify only the production copy.