@alfred.westerveld/astro-compress-html-fast 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# @alfred.westerveld/astro-compress-html-fast
+
+Fast, conservative post-build HTML compression 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
+
+```sh
+npm install @alfred.westerveld/astro-compress-html-fast
+pnpm add @alfred.westerveld/astro-compress-html-fast
+yarn add @alfred.westerveld/astro-compress-html-fast
+bun add @alfred.westerveld/astro-compress-html-fast
+```
+
+## Usage
+
+```ts
+import { defineConfig } from "astro/config";
+import compressHtml from "@alfred.westerveld/astro-compress-html-fast";
+
+export default defineConfig({
+  integrations: [
+    compressHtml({
+      minifyHtml: true,
+      minifyInlineJs: true,
+      minifyInlineCss: true,
+    }),
+  ],
+});
+```
+
+## Options
+
+```ts
+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:
+
+```text
+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

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { AstroIntegration } from 'astro';
+
+interface CompressHtmlOptions {
+    minifyHtml?: boolean;
+    minifyInlineJs?: boolean;
+    minifyInlineCss?: boolean;
+    failOnError?: boolean;
+    verbose?: boolean;
+    target?: string;
+    include?: string[];
+    exclude?: string[];
+}
+
+declare function compressHtml(userOptions?: CompressHtmlOptions): AstroIntegration;
+
+export { type CompressHtmlOptions, compressHtml as default };

package/dist/index.js

@@ -0,0 +1,294 @@
+// src/index.ts
+import { readFile, writeFile } from "fs/promises";
+
+// src/minifyHtml.ts
+import { minify } from "@swc/html";
+import { transform } from "esbuild";
+var rawTextElementPattern = /<(pre|code|textarea)\b[^>]*>[\s\S]*?<\/\1>/gi;
+var scriptPattern = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+var stylePattern = /<style\b([^>]*)>([\s\S]*?)<\/style>/gi;
+async function minifyHtml(html, options) {
+  const protectedRegions = [];
+  const withScripts = await processScripts(html, options, protectedRegions);
+  const withStyles = await processStyles(withScripts, options, protectedRegions);
+  const protectedHtml = protectRawTextElements(withStyles, protectedRegions);
+  if (!options.minifyHtml) {
+    return restoreProtectedRegions(protectedHtml, protectedRegions);
+  }
+  try {
+    const result = await minify(protectedHtml, {
+      collapseWhitespaces: "conservative",
+      removeComments: false,
+      removeEmptyAttributes: false,
+      removeRedundantAttributes: "none",
+      collapseBooleanAttributes: false,
+      normalizeAttributes: false,
+      minifyJson: false,
+      minifyJs: false,
+      minifyCss: false,
+      sortSpaceSeparatedAttributeValues: false,
+      sortAttributes: false,
+      tagOmission: false,
+      selfClosingVoidElements: false,
+      quotes: true
+    });
+    if (result.errors && result.errors.length > 0) {
+      throw new Error(result.errors.map((error) => error.message).join("; "));
+    }
+    return restoreProtectedRegions(result.code, protectedRegions);
+  } catch (error) {
+    if (options.failOnError) {
+      throw toError(error, "Could not minify HTML");
+    }
+    const fallback = conservativeWhitespacePass(protectedHtml);
+    return restoreProtectedRegions(fallback, protectedRegions);
+  }
+}
+async function processScripts(html, options, protectedRegions) {
+  const replacements = Array.from(html.matchAll(scriptPattern), async (match) => {
+    const fullMatch = match[0];
+    const attributes = match[1] ?? "";
+    const content = match[2] ?? "";
+    const replacement = await minifyScriptBlock(
+      fullMatch,
+      attributes,
+      content,
+      options
+    );
+    return {
+      fullMatch,
+      replacement: protect(replacement, protectedRegions)
+    };
+  });
+  const resolved = await Promise.all(replacements);
+  return replaceMatches(html, resolved);
+}
+async function processStyles(html, options, protectedRegions) {
+  const replacements = Array.from(html.matchAll(stylePattern), async (match) => {
+    const fullMatch = match[0];
+    const attributes = match[1] ?? "";
+    const content = match[2] ?? "";
+    const replacement = await minifyStyleBlock(
+      fullMatch,
+      attributes,
+      content,
+      options
+    );
+    return {
+      fullMatch,
+      replacement: protect(replacement, protectedRegions)
+    };
+  });
+  const resolved = await Promise.all(replacements);
+  return replaceMatches(html, resolved);
+}
+async function minifyScriptBlock(original, attributes, content, options) {
+  if (!options.minifyInlineJs || !isMinifiableScript(attributes)) {
+    return original;
+  }
+  try {
+    const transformOptions = {
+      loader: "js",
+      minify: true,
+      target: options.target
+    };
+    if (scriptIsModule(attributes)) {
+      transformOptions.format = "esm";
+    }
+    const result = await transform(content, {
+      ...transformOptions
+    });
+    return `<script${attributes}>${result.code.trim()}</script>`;
+  } catch (error) {
+    if (options.failOnError) {
+      throw toError(error, "Could not minify inline script");
+    }
+    return original;
+  }
+}
+async function minifyStyleBlock(original, attributes, content, options) {
+  if (!options.minifyInlineCss) {
+    return original;
+  }
+  try {
+    const result = await transform(content, {
+      loader: "css",
+      minify: true,
+      target: options.target
+    });
+    return `<style${attributes}>${result.code.trim()}</style>`;
+  } catch (error) {
+    if (options.failOnError) {
+      throw toError(error, "Could not minify inline style");
+    }
+    return original;
+  }
+}
+function isMinifiableScript(attributes) {
+  if (/\ssrc\s*=/i.test(attributes)) {
+    return false;
+  }
+  const type = getAttributeValue(attributes, "type");
+  if (!type) {
+    return true;
+  }
+  const normalizedType = type.trim().toLowerCase();
+  return normalizedType === "module" || normalizedType === "text/javascript" || normalizedType === "application/javascript";
+}
+function scriptIsModule(attributes) {
+  const type = getAttributeValue(attributes, "type");
+  return type?.trim().toLowerCase() === "module";
+}
+function getAttributeValue(attributes, name) {
+  const pattern = new RegExp(
+    `(?:^|\\s)${escapeRegExp(name)}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'=<>\`]+))`,
+    "i"
+  );
+  const match = pattern.exec(attributes);
+  return match?.[1] ?? match?.[2] ?? match?.[3];
+}
+function protectRawTextElements(html, protectedRegions) {
+  return html.replace(
+    rawTextElementPattern,
+    (content) => protect(content, protectedRegions)
+  );
+}
+function protect(content, protectedRegions) {
+  const placeholder = `<!--astro-compress-html-fast:${protectedRegions.length}-->`;
+  protectedRegions.push({ placeholder, content });
+  return placeholder;
+}
+function restoreProtectedRegions(html, protectedRegions) {
+  return protectedRegions.reduce(
+    (result, region) => result.split(region.placeholder).join(region.content),
+    html
+  );
+}
+function conservativeWhitespacePass(html) {
+  return html.replace(/>\s+</g, "><").replace(/[ \t\f\r\n]{2,}/g, " ").trim();
+}
+function replaceMatches(html, replacements) {
+  return replacements.reduce(
+    (result, replacement) => result.replace(replacement.fullMatch, replacement.replacement),
+    html
+  );
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function toError(error, fallbackMessage) {
+  return error instanceof Error ? error : new Error(fallbackMessage);
+}
+
+// src/options.ts
+function normalizeOptions(options = {}) {
+  return {
+    minifyHtml: options.minifyHtml ?? true,
+    minifyInlineJs: options.minifyInlineJs ?? false,
+    minifyInlineCss: options.minifyInlineCss ?? false,
+    failOnError: options.failOnError ?? false,
+    verbose: options.verbose ?? false,
+    target: options.target ?? "es2020",
+    include: options.include ?? ["**/*.html"],
+    exclude: options.exclude ?? []
+  };
+}
+
+// src/report.ts
+function createSummary(results) {
+  return results.reduce(
+    (summary, result) => ({
+      files: summary.files + 1,
+      changed: summary.changed + (result.changed ? 1 : 0),
+      skipped: summary.skipped + (result.skipped ? 1 : 0),
+      originalBytes: summary.originalBytes + result.originalBytes,
+      compressedBytes: summary.compressedBytes + result.compressedBytes
+    }),
+    {
+      files: 0,
+      changed: 0,
+      skipped: 0,
+      originalBytes: 0,
+      compressedBytes: 0
+    }
+  );
+}
+function formatByteDelta(summary) {
+  const savedBytes = summary.originalBytes - summary.compressedBytes;
+  const percentage = summary.originalBytes === 0 ? "0.0" : (savedBytes / summary.originalBytes * 100).toFixed(1);
+  return `${summary.compressedBytes}/${summary.originalBytes} bytes (${savedBytes} saved, ${percentage}%)`;
+}
+function reportSummary(reporter, summary, verbose) {
+  if (!verbose && summary.changed === 0) {
+    return;
+  }
+  reporter.info(
+    `compressed ${summary.changed}/${summary.files} HTML files; ${formatByteDelta(summary)}`
+  );
+}
+
+// src/walkHtmlFiles.ts
+import { fileURLToPath } from "url";
+import { glob } from "tinyglobby";
+async function walkHtmlFiles(outDir, options) {
+  const cwd = fileURLToPath(outDir);
+  const files = await glob(options.include, {
+    cwd,
+    absolute: true,
+    onlyFiles: true,
+    ignore: options.exclude
+  });
+  return files.sort();
+}
+
+// src/index.ts
+function compressHtml(userOptions = {}) {
+  const options = normalizeOptions(userOptions);
+  return {
+    name: "astro-compress-html-fast",
+    hooks: {
+      "astro:build:done": async ({ dir, logger }) => {
+        const files = await walkHtmlFiles(dir, options);
+        const results = [];
+        for (const filePath of files) {
+          try {
+            const original = await readFile(filePath, "utf8");
+            const compressed = await minifyHtml(original, options);
+            const originalBytes = Buffer.byteLength(original);
+            const compressedBytes = Buffer.byteLength(compressed);
+            const shouldWrite = compressed.length > 0 && compressedBytes < originalBytes;
+            if (shouldWrite) {
+              await writeFile(filePath, compressed);
+            }
+            results.push({
+              filePath,
+              originalBytes,
+              compressedBytes: shouldWrite ? compressedBytes : originalBytes,
+              changed: shouldWrite,
+              skipped: false
+            });
+          } catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown minification error";
+            if (options.failOnError) {
+              throw error;
+            }
+            logger.warn(`Could not compress ${filePath}: ${message}`);
+            const original = await readFile(filePath, "utf8");
+            const originalBytes = Buffer.byteLength(original);
+            results.push({
+              filePath,
+              originalBytes,
+              compressedBytes: originalBytes,
+              changed: false,
+              skipped: true
+            });
+          }
+        }
+        reportSummary(logger, createSummary(results), options.verbose);
+      }
+    }
+  };
+}
+export {
+  compressHtml as default
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@alfred.westerveld/astro-compress-html-fast",
+  "version": "0.1.0",
+  "description": "Fast, conservative post-build HTML compression for Astro.",
+  "type": "module",
+  "license": "MIT",
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "keywords": [
+    "astro",
+    "integration",
+    "html",
+    "minify",
+    "compress"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "bun run typecheck && bun run test && bun run build"
+  },
+  "peerDependencies": {
+    "astro": ">=4 <7"
+  },
+  "dependencies": {
+    "@swc/html": "^1.15.41",
+    "esbuild": "^0.27.3",
+    "tinyglobby": "^0.2.15"
+  },
+  "devDependencies": {
+    "astro": "6.4.4",
+    "@types/node": "^24.10.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}