esbuild-single-html

An esbuild plugin to bundle referenced JavaScript/TypeScript scripts and CSS stylesheets directly into a single, standalone HTML file.

This plugin allows you to use HTML files as entry points in esbuild. It parses the HTML, finds external scripts (<script src="...">) and styles (<link rel="stylesheet" href="...">), bundles them using esbuild, and inlines the bundled content into the output HTML.

Features

• Use HTML files as entry points in esbuild.
• Automatically compile and bundle TypeScript/JavaScript referenced via <script src="...">.
• Minify and inline CSS stylesheets referenced via <link rel="stylesheet">.
• Outputs a single, self-contained HTML file (perfect for single-page applications, web components, offline tools, etc.).
• Extensible using custom asset processors.

Installation

npm install --save-dev esbuild-single-html esbuild

[!NOTE] esbuild is defined as a peer dependency. Make sure you have esbuild installed in your project.

Usage

Create your HTML, TypeScript/JavaScript, and CSS files:

src/index.html

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>Single HTML App</title>
  <link rel="stylesheet" href="./style.css">
</head>
<body>
  <h1>Hello World!</h1>
  <script src="./main.ts"></script>
</body>
</html>

src/main.ts

const heading = document.querySelector('h1');
if (heading) {
  heading.textContent = 'Hello from TypeScript!';
}

src/style.css

body {
  background-color: #f0f2f5;
  font-family: sans-serif;
}

Then configure and run esbuild:

build.js

const esbuild = require('esbuild');
const { singleHtmlPlugin } = require('esbuild-single-html');

esbuild.build({
  entryPoints: ['src/index.html'],
  outfile: 'dist/index.html',
  bundle: true,
  minify: true,
  plugins: [
    singleHtmlPlugin()
  ],
}).catch(() => process.exit(1));

Run the build script:

node build.js

The output dist/index.html will contain the bundled JavaScript and CSS inlined into a single file.

Options

singleHtmlPlugin accepts the following options:

| Option | Type | Description | | :--- | :--- | :--- | | esbuildOptions | BuildOptions | Custom esbuild options applied when bundling individual JS/TS assets (e.g. define, target, loader). | | extraProcessors | AssetProcessor[] | Additional custom asset processors to extend the HTML processing behavior (e.g. image inline processors). |

Custom Processors

You can extend the plugin with custom processors that implement the AssetProcessor interface:

import { AssetProcessor } from 'esbuild-single-html';

const customProcessor: AssetProcessor = {
  name: 'my-custom-processor',
  test: (element) => {
    // Return true if this processor should handle the element
    return element.name === 'img' && element.attribs.src?.startsWith('./');
  },
  process: async (element, context) => {
    // Process the element and modify it in-place
    // e.g., convert image src to Data URL
  }
};

License

MIT