{"id":25347,"library":"esbuild-plugin-html-modules","title":"esbuild-plugin-html-modules","description":"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.","status":"active","version":"0.9.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","esbuild","esbuild-plugin"],"install":[{"cmd":"npm install esbuild-plugin-html-modules","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-plugin-html-modules","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-plugin-html-modules","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; plugin runs inside esbuild build process","package":"esbuild","optional":false}],"imports":[{"note":"Package exports a default function; CJS users must use the default export correctly.","wrong":"const htmlModulesPlugin = require('esbuild-plugin-html-modules').default","symbol":"htmlModulesPlugin (default)","correct":"import htmlModulesPlugin from 'esbuild-plugin-html-modules'"},{"note":"Named export available in v0.7+; identical to default export.","wrong":"import { default as htmlModulesPlugin } from 'esbuild-plugin-html-modules'","symbol":"htmlModulesPlugin (named)","correct":"import { htmlModulesPlugin } from 'esbuild-plugin-html-modules'"},{"note":"Options type is exported, but only as a type; use `import type` to avoid runtime errors.","wrong":"import { HtmlModulesPluginOptions } from 'esbuild-plugin-html-modules'","symbol":"type options","correct":"import type { HtmlModulesPluginOptions } from 'esbuild-plugin-html-modules'"}],"quickstart":{"code":"// quickstart.js\nimport * as esbuild from 'esbuild';\nimport htmlModulesPlugin from 'esbuild-plugin-html-modules';\n\nawait esbuild.build({\n  bundle: true,\n  entryPoints: ['src/index.js'],\n  outfile: 'dist/bundle.js',\n  plugins: [\n    htmlModulesPlugin({\n      filter: /\\.html$/,\n      experimental: {\n        extractGlobalStyles: true,\n        transformLocalStyles: async (css, { filePath }) => {\n          // Example: use PostCSS for transformation\n          const postcss = (await import('postcss')).default;\n          const result = await postcss([\n            require('autoprefixer')\n          ]).process(css, { from: filePath });\n          return result.css;\n        }\n      }\n    })\n  ]\n});\n\nconsole.log('Build complete!');","lang":"javascript","description":"Shows how to set up esbuild with htmlModulesPlugin, including global style extraction and local style transformation with PostCSS."},"warnings":[{"fix":"Replace `extractScopedStyles: true` with `extractGlobalStyles: true` and use standard CSS nesting or `@scope` for scoped styles.","message":"The `extractScopedStyles: true` option was removed in v0.8. Use `extractGlobalStyles` or shadow DOM styles instead.","severity":"breaking","affected_versions":">=0.8"},{"fix":"Use `import { htmlModulesPlugin } from 'esbuild-plugin-html-modules'` instead of the default import.","message":"The default export `htmlModulesPlugin` is deprecated in favor of the named export. The default export will be removed in v1.0.","severity":"deprecated","affected_versions":">=0.9"},{"fix":"Use `const htmlModulesPlugin = require('esbuild-plugin-html-modules').default;`","message":"CJS require must use `.default` property to access the plugin function.","severity":"gotcha","affected_versions":"*"},{"fix":"Use a RegExp, e.g., `filter: /\\.html$/`.","message":"The `filter` option must be a RegExp. Passing a string will cause unexpected behavior.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run `npm install esbuild-plugin-html-modules --save-dev`.","cause":"Package not installed or missing from dependencies.","error":"Cannot find module 'esbuild-plugin-html-modules'"},{"fix":"Change to `const htmlModulesPlugin = require('esbuild-plugin-html-modules').default;`","cause":"Using CJS `require` without `.default`.","error":"TypeError: htmlModulesPlugin is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}