Registry / web-framework / esbuild-plugin-html-modules

esbuild-plugin-html-modules

library0.9.1jsnpmunverified

An esbuild plugin that enables loading HTML files as ES modules, following the WICG HTML Modules proposal. Version 0.9.1 allows importing HTML files with `import` statements, where the HTML template becomes the default export and `<script type="module">` code runs as the module script. Supports configuration for global CSS extraction, local style transformation via PostCSS, and custom file filters. Key differentiator: enables web component authors to co-locate templates, scripts, and styles in single HTML files with standard ES module semantics. Released weekly, actively maintained.

web-framework serialization

npm install esbuild-plugin-html-modules

package ↗homepage ↗

INSTALL

IMPORT

SIG · ESBUILD-PLUGIN-HTM

esbuild-plugin-html-modules

web-frameworkjavascriptv0.9.1

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.

htmlModulesPlugin (default)

✓ import htmlModulesPlugin from 'esbuild-plugin-html-modules'

✗ const htmlModulesPlugin = require('esbuild-plugin-html-modules').default

Package exports a default function; CJS users must use the default export correctly.

htmlModulesPlugin (named)

✓ import { htmlModulesPlugin } from 'esbuild-plugin-html-modules'

✗ import { default as htmlModulesPlugin } from 'esbuild-plugin-html-modules'

Named export available in v0.7+; identical to default export.

type options

✓ import type { HtmlModulesPluginOptions } from 'esbuild-plugin-html-modules'

✗ import { HtmlModulesPluginOptions } from 'esbuild-plugin-html-modules'

Options type is exported, but only as a type; use `import type` to avoid runtime errors.

Shows how to set up esbuild with htmlModulesPlugin, including global style extraction and local style transformation with PostCSS.

// quickstart.js import * as esbuild from 'esbuild'; import htmlModulesPlugin from 'esbuild-plugin-html-modules'; await esbuild.build({ bundle: true, entryPoints: ['src/index.js'], outfile: 'dist/bundle.js', plugins: [ htmlModulesPlugin({ filter: /\.html$/, experimental: { extractGlobalStyles: true, transformLocalStyles: async (css, { filePath }) => { // Example: use PostCSS for transformation const postcss = (await import('postcss')).default; const result = await postcss([ require('autoprefixer') ]).process(css, { from: filePath }); return result.css; } } }) ] }); console.log('Build complete!');

Debug

Known issues

breakingThe `extractScopedStyles: true` option was removed in v0.8. Use `extractGlobalStyles` or shadow DOM styles instead.

fix

Replace `extractScopedStyles: true` with `extractGlobalStyles: true` and use standard CSS nesting or `@scope` for scoped styles.

affects: >=0.8

deprecatedThe default export `htmlModulesPlugin` is deprecated in favor of the named export. The default export will be removed in v1.0.

fix

Use `import { htmlModulesPlugin } from 'esbuild-plugin-html-modules'` instead of the default import.

affects: >=0.9

gotchaCJS require must use `.default` property to access the plugin function.

fix

Use `const htmlModulesPlugin = require('esbuild-plugin-html-modules').default;`

affects: *

gotchaThe `filter` option must be a RegExp. Passing a string will cause unexpected behavior.

fix

Use a RegExp, e.g., `filter: /\.html$/`.

affects: *

Errors

Common errors & fixes

Cannot find module 'esbuild-plugin-html-modules'

Package not installed or missing from dependencies.

fix

Run `npm install esbuild-plugin-html-modules --save-dev`.

TypeError: htmlModulesPlugin is not a function

Using CJS `require` without `.default`.

fix

Change to `const htmlModulesPlugin = require('esbuild-plugin-html-modules').default;`

Upgrade

Version history

0.9.1latest on npm

Audit

Dependencies

esbuildrequiredPeer dependency; plugin runs inside esbuild build process

Agent activity

6 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/esbuild-plugin-html-modules ↗

homepagehttps://codeberg.org/jaredwhite/esbuild-plugin-html-modules#readme ↗