babel-plugin-template-html-minifier

4.1.0 verified Fri May 01 auth: no javascript

A Babel plugin that minifies HTML in tagged template strings using html-minifier-terser. Current stable version: 4.1.0. It supports popular libraries like lit-html, lit-element, choo, and hyperHTML. The plugin integrates directly into the Babel pipeline, allowing compile-time minification without runtime overhead. It offers configurable html-minifier options and strict CSS validation mode. Unlike runtime minifiers, this plugin performs minification during build, reducing bundle size and improving performance. It requires Node >=10.13.0.

Common errors

error Error: `removeComments` is not safe when template contains expression inside comment ↓

cause html-minifier removes comments including dynamic expressions, which changes behavior

fix

Set htmlMinifier.removeComments to false or ensure no dynamic expressions inside comments

error Error: `collapseBooleanAttributes` is not safe when template contains expression in boolean attribute ↓

cause Minifier collapses boolean attributes and removes the placeholder for the expression

fix

Set htmlMinifier.collapseBooleanAttributes to false

error The plugin name must be 'template-html-minifier' not 'babel-plugin-template-html-minifier' ↓

cause Babel expects the short name without the babel-plugin- prefix when using array format

fix

Use ['template-html-minifier', options] in plugins

Warnings

breaking HTML template containing dynamic expressions inside comments will throw an error ↓

fix Use eslint-plugin-lit's binding-positions rule to catch invalid bindings before build

breaking Use of collapseBooleanAttributes option breaks lit-html templates with dynamic attributes ↓

fix Set htmlMinifier.collapseBooleanAttributes to false (or omit it)

deprecated Plugin name used to be 'babel-plugin-template-html-minifier' but in Babel config it should be 'template-html-minifier' ↓

fix Use 'template-html-minifier' in plugins array

gotcha strictCSS: true prevents minification of incomplete CSS template parts, may leave CSS unminified ↓

fix Only enable strictCSS if you use patterns like lit-element's css template that concatenate fragments

Install

npm install babel-plugin-template-html-minifier

yarn add babel-plugin-template-html-minifier

pnpm add babel-plugin-template-html-minifier

Imports

Plugin config

wrong

// Wrong plugin name
{
  "plugins": ["babel-plugin-template-html-minifier"]
}

correct

// In .babelrc or babel.config.js:
{
  "plugins": [
    ["template-html-minifier", { "modules": { "lit-html": ["html"] } }]
  ]
}

Plugin name in Babel config is 'template-html-minifier' (without '@babel/' prefix). The second element in the array is the options object.

Programmatic usage

wrong

const plugin = require('babel-plugin-template-html-minifier');
// plugin is a function, not a default export

correct

import plugin from 'babel-plugin-template-html-minifier';
// passes options as second argument to Babel transform

This package is a Babel plugin, usually consumed via Babel config. Programmatic usage: import and pass to Babel's transform function.

TypeScript

wrong

import plugin from 'babel-plugin-template-html-minifier';
// TypeScript may complain about missing module

correct

// No TypeScript types are bundled; use @types/babel__core for plugin typings

If using TypeScript, install @types/babel__core for plugin support. No ambient types provided.

Quickstart

Shows how to configure the plugin to minify lit-html templates in Babel.

// Create a JavaScript file with a tagged template:
import { html } from 'lit-html';

const title = 'Hello World';
const template = html`
  <div class="container">
    <h1>${title}</h1>
    <p>Some text</p>
  </div>
`;

// .babelrc:
{
  "plugins": [
    ["template-html-minifier", {
      "modules": {
        "lit-html": ["html"]
      },
      "htmlMinifier": {
        "collapseWhitespace": true,
        "removeComments": true
      }
    }]
  ]
}

// After Babel transformation, the template will be minified:
// const template = html`
//   <div class="container"><h1>${title}</h1><p>Some text</p></div>
// `;