astro-html-minifier-next

Minify Astro HTML assets using html-minifier-next!

• Improves page speed - Reduces the size of HTML assets by removing everything unnecessary.
• Highly configurable - All options from html-minifier-next are supported and can be customized.
• Fast - Runs the minification of all assets with (limited) concurrency and Lightning CSS.

import { defineConfig } from "astro/config";
import htmlMinifier from "astro-html-minifier-next";

export default defineConfig({
  integrations: [
    htmlMinifier({
      /* My recommended html-minifier-next options: */
      caseSensitive: true,
      collapseBooleanAttributes: true,
      collapseInlineTagWhitespace: false,
      collapseWhitespace: true,
      conservativeCollapse: false,
      continueOnMinifyError: false,
      continueOnParseError: false,
      decodeEntities: true,
      html5: true,
      includeAutoGeneratedTags: true,
      keepClosingSlash: false,
      minifyCSS: true,
      minifyJS: true,
      minifyURLs: false,
      noNewlinesBeforeTagClose: false,
      preserveLineBreaks: false,
      preventAttributesEscaping: false,
      processConditionalComments: false,
      removeAttributeQuotes: false, // Technically they are optional and can greatly reduce size, but the HTML specification recommends always using quotes.
      removeComments: true,
      removeEmptyAttributes: true,
      removeEmptyElements: false,
      removeOptionalTags: false,
      removeRedundantAttributes: true,
      removeScriptTypeAttributes: true,
      removeStyleLinkTypeAttributes: true,
      removeTagWhitespace: false,
      sortAttributes: false,
      sortClassName: false,
      useShortDoctype: true,
    }),
  ],
});

Installation

Add the integration to your Astro project using the astro add command.
This will install the package and make the appropriate changes to your astro.config.mjs/astro.config.ts file in one step:

npx astro add astro-html-minifier-next

If you prefer to add the integration manually instead, complete the following two steps:

1. Install the package to your project’s dependencies using your preferred package manager.
   If you’re using npm or aren’t sure, run this in the terminal:

   npm install --save-dev astro-html-minifier-next

   Or, if you're using Deno, run this in the terminal:

   deno add jsr:@jonasgeiler/astro-html-minifier-next

2. Add the integration to your astro.config.mjs/astro.config.ts file:

   import { defineConfig } from "astro/config";
   
   // ADD THE FOLLOWING LINE:
   import htmlMinifier from "astro-html-minifier-next";
   
   export default defineConfig({
     // ...
   
     integrations: [
       // ...
   
       // ADD THE FOLLOWING LINE:
       htmlMinifier({ /* Your html-minifier-next options here. */ }),
     ],
   });

Usage

Once installed, the integration will automatically minify all HTML assets generated by Astro during the build process using the provided html-minifier-next options.

Options

You can find a quick reference of all available options in the html-minifier-next documentation.
You can also check out the JSDoc comments in the source code.

There is currently one additional option only specific to this Astro integration. See below.

Tip

To ensure consistent and wide browser support throughout your project, I recommend setting the targets property of the minifyCSS option to your project's Browserslist query. This configures Lightning CSS (the CSS minifier used by html-minifier-next) to properly optimize the CSS according to the browsers you want to support.

You can do this, by adding the following lines to your astro.config.mjs/astro.config.ts file:

import { defineConfig } from "astro/config";
import htmlMinifier from "astro-html-minifier-next";

// ADD THE FOLLOWING LINES:
import browserslist from "browserslist";
import { browserslistToTargets } from "lightningcss";

export default defineConfig({
  // ...

  integrations: [
    // ...

    htmlMinifier({
      // ...

      minifyCSS: {
        // ...

        // ADD THE FOLLOWING LINE:
        targets: browserslistToTargets(browserslist("defaults")),
      },
    }),
  ],
});

More information can be found in the Lightning CSS documentation.

alwaysWriteMinifiedHTML

This option is not passed to html-minifier-next. It only controls the behavior of this Astro integration.

By default, the integration only overwrites the original HTML assets if the minified HTML is smaller. However, there are cases where you might actually prefer the larger output due to special compatibility reasons or otherwise.
Setting this option to true causes the integration to always overwrite the HTML assets with their minified results, regardless of size.

Credits

This project wouldn't be possible without the awesome work of Juriy Zaytsev aka. @kangax (html-minifier), the Terser team (html-minifier-terser), and of course Jens Oliver Meiert aka. @j9t (html-minifier-next).