esbuild-plugin-minify-html

0.1.2 verified Fri May 01 auth: no javascript

An esbuild plugin that imports HTML files as minified raw text strings at build time, using html-minifier-terser for minification. Version 0.1.2 is the current stable release, with infrequent updates. It differentiates itself from raw-text loaders by combining import and minification in one plugin, eliminating the need for a separate minification step. Ships TypeScript types and supports customizable minifier options like collapseWhitespace.

Common errors

error Error: No matching plugins for import "*.html?raw" ↓

cause Plugin not registered in esbuild configuration or ?raw suffix omitted.

fix

Add minifyHTML plugin to esbuild.plugins array and ensure import path ends with ?raw.

error Cannot find module '*.html?raw' or its corresponding type declarations. ↓

cause TypeScript does not recognize .html?raw imports without a module declaration.

fix

Place a .d.ts file in your project root with: declare module '*.html?raw' { const src: string; export default src; }

error Error: Cannot find module 'html-minifier-terser' ↓

cause Missing required peer dependency html-minifier-terser.

fix

Run: npm install html-minifier-terser

Warnings

gotcha Query suffix ?raw is required on HTML imports; omitting it bypasses the plugin and may cause build errors or undefined imports. ↓

fix Always append ?raw to HTML import paths: import content from './file.html?raw'

gotcha TypeScript users must add a module declaration for *.html?raw to avoid type errors. ↓

fix Add a .d.ts file with: declare module '*.html?raw' { const src: string; export default src; }

breaking Version 0.1.0 changed from esbuild-plugin-raw-css to esbuild-plugin-minify-html; all import paths and plugin API changed. ↓

fix Migrate to new package: npm install esbuild-plugin-minify-html and update imports

gotcha html-minifier-terser options are passed directly to the minifier; some options may break HTML semantics if misconfigured. ↓

fix Refer to html-minifier-terser documentation and test minified output for correctness

Install

npm install esbuild-plugin-minify-html

yarn add esbuild-plugin-minify-html

pnpm add esbuild-plugin-minify-html

Imports

default (minifyHTML)
wrong
```
const minifyHTML = require('esbuild-plugin-minify-html')
```
correct
```
import minifyHTML from 'esbuild-plugin-minify-html'
```
Package exports ESM default; CJS require works but may fail if bundler lacks ESM interop
HTML file import with ?raw
wrong
```
import content from './file.html'
```
correct
```
import content from './file.html?raw'
```
The ?raw query suffix is required to trigger the plugin; TypeScript needs a module declaration for ?raw imports

TypeScript module declaration

wrong

declare module '*.html' { const src: string; export default src; }

correct

declare module '*.html?raw' { const src: string; export default src; }

The ?raw suffix must be included in the module declaration to match the import syntax

Quickstart

Build script using esbuild with minifyHTML plugin to import and minify HTML files as raw text.

import esbuild from 'esbuild';
import minifyHTML from 'esbuild-plugin-minify-html';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/out.js',
  plugins: [
    minifyHTML({
      collapseWhitespace: true,
      removeComments: true,
    }),
  ],
});