esbuild-html-plugin

1.1.0 verified Fri May 01 auth: no javascript

An esbuild plugin that generates an HTML file with output URLs of bundled assets. Version 1.1.0, released as stable. It provides fine-grained control over HTML head and body elements through callback functions, allowing dynamic injection of CSS and JS references. Unlike alternative HTML plugins for esbuild, this one is minimalistic and avoids bundling HTML templates, focusing solely on generating a simple HTML file with asset URLs. No HTML minification is included since v1.1.0. The package is ESM-only, small, and has no runtime dependencies.

Common errors

error Error: Cannot find module 'esbuild-html-plugin' ↓

cause Missing installation or ESM-only package used with require()

fix

Run 'npm install esbuild-html-plugin' and use 'import' syntax.

error TypeError: htmlPlugin is not a function ↓

cause Default import used instead of named import

fix

Change to 'import { htmlPlugin } from 'esbuild-html-plugin''.

error Error: The plugin "html-plugin" must be an object with a "name" and "setup" function ↓

cause Misconfigured plugin parameter; likely passed undefined or wrong shape

fix

Ensure htmlPlugin is called: htmlPlugin({ outfile: 'index.html' }).

Warnings

breaking HTML minification feature removed in v1.1.0 ↓

fix Remove any minification options. If needed, use a separate minification step.

deprecated Default export removed; use named export htmlPlugin ↓

fix Change import to named export.

gotcha outfile must be provided; outdir or esbuild's outfile must be set or the HTML won't be generated ↓

fix Ensure outfile is set and esbuild's outdir or outfile is configured.

gotcha createHeadElements and createBodyElements receive output URLs; they may be absolute or relative depending on publicPath ↓

fix Handle URLs as provided; use publicPath to control prefix.

Install

npm install esbuild-html-plugin

yarn add esbuild-html-plugin

pnpm add esbuild-html-plugin

Imports

htmlPlugin

wrong

const htmlPlugin = require('esbuild-html-plugin')

correct

import { htmlPlugin } from 'esbuild-html-plugin'

Package is ESM-only; require() will fail.

htmlPlugin
wrong
```
import htmlPlugin from 'esbuild-html-plugin'
```
correct
```
import { htmlPlugin } from 'esbuild-html-plugin'
```
Named export, not default. v1.0.1 added types to package.json, so TypeScript works.
HtmlPluginOptions
```
import type { HtmlPluginOptions } from 'esbuild-html-plugin'
```
Available as a type export for TypeScript users.

Quickstart

Builds an esbuild bundle and generates an index.html with script tags for JS outputs.

import * as esbuild from 'esbuild';
import { htmlPlugin } from 'esbuild-html-plugin';

await esbuild.build({
  entryPoints: ['app.ts'],
  bundle: true,
  outdir: 'dist',
  publicPath: '/static',
  plugins: [
    htmlPlugin({
      outfile: 'index.html',
      createHeadElements: () => [
        `<meta charset="utf-8" />`,
        `<meta name="viewport" content="width=device-width, initial-scale=1" />`,
        `<title>Example</title>`,
      ],
      createBodyElements: (outputUrls) =>
        outputUrls
          .filter((url) => url.endsWith('.js'))
          .map((url) => `<script src="${url}"></script>`),
    }),
  ],
});