Registry / devops / metalsmith-optimize-html

metalsmith-optimize-html

library0.10.0jsnpmunverified

A Metalsmith plugin for optimizing and minifying HTML files. Current stable version: 0.10.0. Release cadence: irregular, maintained by GitHub user wernerglinka. Key differentiators: single-pass tokenizer for high performance (300x improvement over regex-based alternatives), modular architecture with fine-grained control over optimizations, dual ESM/CommonJS support, built from scratch to replace the abandoned metalsmith-html-minifier with modern JavaScript practices and minimal dependencies.

devops

npm install metalsmith-optimize-html

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · METALSMITH-OPTIMIZ

metalsmith-optimize-html

devopsjavascriptv0.10.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import optimizeHTML from 'metalsmith-optimize-html'

✗ const optimizeHTML = require('metalsmith-optimize-html')

ESM is recommended as the primary module format; CommonJS require is also supported but may exhibit issues in mixed-module projects.

default

✓ const optimizeHTML = require('metalsmith-optimize-html')

✗ import { optimizeHTML } from 'metalsmith-optimize-html'

CommonJS require is supported via the default export; named import does not exist.

default

✓ import optimizeHTML from 'metalsmith-optimize-html'

TypeScript users may need to set esModuleInterop: true for default import to work.

Basic Metalsmith setup with HTML optimization plugin, processing HTML files with comment removal and tag space stripping.

import Metalsmith from 'metalsmith'; import optimizeHTML from 'metalsmith-optimize-html'; import { fileURLToPath } from 'url'; import path from 'path'; const __dirname = path.dirname(fileURLToPath(import.meta.url)); Metalsmith(__dirname) .source('./src') .destination('./build') .use( optimizeHTML({ removeComments: true, removeTagSpaces: true, simplifyDoctype: true, pattern: '**/*.html', excludeTags: ['pre', 'code'] }) ) .build((err) => { if (err) throw err; console.log('Build complete!'); });

Debug

Known issues

gotchaThe plugin only processes files matching the 'pattern' glob (default '**/*.html'). Ensure your HTML files have the .html extension or override the pattern.

fix

Explicitly set pattern: '**/*.{html,htm}' in options.

affects: >=0.10.0

deprecatedThe 'aggressive: true' option enables all optimizations but may break HTML functionality. Use with caution and test output.

fix

Manually enable only the optimizations you need to avoid unintended side effects.

affects: >=0.10.0

gotchaThe plugin does not process files that have been directly read by other plugins prior to this plugin in the middleware chain.

fix

Place metalsmith-optimize-html after any plugins that read/transform HTML content, but before any final build steps.

affects: >=0.10.0

gotchaNon-UTF-8 character encodings may cause unexpected behavior as the plugin assumes UTF-8 input.

fix

Ensure HTML files are UTF-8 encoded before processing.

affects: >=0.10.0

Errors

Common errors & fixes

TypeError: optimizeHTML is not a function

Using named import instead of default import in ESM.

fix

Use `import optimizeHTML from 'metalsmith-optimize-html'` or `const optimizeHTML = require('metalsmith-optimize-html')`.

Error: Plugin must be a function

Passing options object directly to .use() without wrapping in the plugin function.

fix

Wrap options in the plugin call: `.use(optimizeHTML({...}))`.

Error: Cannot find module 'metalsmith'

Missing metalsmith as a peer dependency.

fix

Run `npm install metalsmith` to add it to your project.

SyntaxError: Unexpected token 'export'

Using ESM import syntax in a CommonJS module without proper package.json type field or .mjs extension.

fix

Use `require` for CommonJS or set `"type": "module"` in package.json and use .mjs extension if needed.

Upgrade

Version history

0.10.0latest on npm

Audit

Dependencies

metalsmithrequiredPeer dependency; required as the build tool framework

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/wernerglinka/metalsmith-optimize-html ↗

packagemetalsmith-optimize-html ↗

homepagehttps://github.com/wernerglinka/metalsmith-optimize-html#readme ↗