astro-crunch

Fast, conservative post-build HTML crunching for Astro.

This Astro integration runs after astro build, walks generated HTML files, and writes smaller output back to the build directory. It does not transform source .astro files.

Install

npm install astro-crunch
pnpm add astro-crunch
yarn add astro-crunch
bun add astro-crunch

Usage

import { defineConfig } from "astro/config";
import compressHtml from "astro-crunch";

export default defineConfig({
  integrations: [
    compressHtml({
      minifyHtml: true,
      minifyInlineJs: true,
      minifyInlineCss: true,
    }),
  ],
});

Options

interface CompressHtmlOptions {
  minifyHtml?: boolean;
  minifyInlineJs?: boolean;
  minifyInlineCss?: boolean;
  failOnError?: boolean;
  verbose?: boolean;
  target?: string;
  include?: string[];
  exclude?: string[];
}

| Option | Default | Description | | --- | --- | --- | | minifyHtml | true | Minify generated HTML with conservative @swc/html settings. | | minifyInlineJs | false | Minify eligible inline classic/module scripts with esbuild. | | minifyInlineCss | false | Minify inline <style> blocks with esbuild. | | failOnError | false | Throw on the first failed file instead of warning and keeping the original. | | verbose | false | Print a before/after byte summary even when no files changed. | | target | "es2020" | JavaScript/CSS target passed to esbuild. | | include | ["**/*.html"] | Glob patterns matched inside Astro's output directory. | | exclude | [] | Glob patterns ignored inside Astro's output directory. |

Safety Notes

The integration protects these regions before whole-document HTML minification:

• <pre>
• <code>
• <textarea>
• external scripts
• JSON-LD scripts
• import maps
• unknown or non-JS script types

Inline JavaScript and CSS minification are opt-in because those blocks often contain framework data, templates, or code with assumptions outside normal bundled assets.

The default HTML pass avoids aggressive rewrites such as optional tag removal, attribute sorting, quote removal, boolean attribute collapsing, and attribute normalization.

Reporting

When files are changed, the integration reports how many HTML files were compressed and the before/after byte count:

compressed 4/4 HTML files; 18400/22120 bytes (3720 saved, 16.8%)

Use verbose: true to always print the summary.

When Not To Use This

Do not use this package when:

• another post-build HTML optimizer is already responsible for generated HTML
• your deployment or tests depend on exact generated HTML bytes
• pages contain unusual whitespace-sensitive markup outside protected elements
• gzip or Brotli already gives enough benefit and build-time HTML rewriting is unnecessary