html-bundle

A (primarily) zero-config bundler for HTML files. The idea is to use HTML as Single File Components, because HTML can already include <style> and <script> elements.

Features

• 🦾 TypeScript (reference it as .js or write inline TS)
• 📦 Automatic Package Installation
• 💨 State-preserving HMR with automatic reconnect and full-reload fallback
• ⚡ ESBuild
• 🦔 Critical CSS
• 🚋 Watcher on PostCSS and Tailwind CSS and TS Config
• 🛡️ Almost no need to restart

Demo

Installation and Usage

$ npm install -D html-bundle

Add an entry to script in package.json (see flags below).

{
  "scripts": {
    "build": "html-bundle"
  }
}

Add a postcss.config.js file and run the build command. If you do not create this config file, a minimal in-memory config file will be created with cssnano as plugin.

$ npm run build

CLI

--hmr: boots up a static server and enables Hot Module Replacement. See HMR for what is hot-patched in place versus reloaded. --secure: creates a secure HTTP2 over HTTPS instance. Plain HTTP requests to the same host and port redirect to HTTPS. This requires the files localhost.pem and localhost-key.pem in the root folder. You can generate them with mkcert for instance. --isCritical: uses critical to extract and inline critical-path CSS to HTML. --licenseNotices: generates THIRD-PARTY-NOTICES.txt. Disabled by default. Missing-license warnings are suppressed during HMR. --handler: path to your custom handler. Here, you can handle all non-supported files. You can get the filename via process.argv[2]. --handlerConcurrency: maximum number of handler processes running at once. Defaults to the available CPU count. For image-heavy handlers such as Sharp resizing, try 2, 4, 8, and the default value, then keep the fastest value that does not spike memory.

HMR

With --hmr, every change is pushed over a single Server-Sent-Events connection and applied without a full reload wherever that is safe:

• HTML (text, attributes, inline <style>) is diffed and patched in place. Only the <script>s whose code actually changed are re-executed, so unrelated state is preserved. Inserting or removing surrounding markup keeps dynamically rendered/fetched content intact.
• CSS (linked or inline) and assets (images, etc.) are swapped by cache-busting the matching element — no reload.
• TS/JS modules are re-bundled; the page(s) that inline them are re-emitted and hot-patched.
• JSON imported by inline TS/JS is bundled by esbuild. JSON changes rebuild pages and hot-patch changed HTML; changes with no changed page trigger a full reload.
• Dead ends — a change with no owning page (e.g. a web-worker entry) or a deleted file — trigger a single debounced full page reload, so you never get stuck on a stale view.
• Server restarts are detected when the EventSource reconnects. The page reloads once so supervised SSR servers return fresh output.

Composed apps (pages that fetch and render other pages) are supported: every live page shares one connection and only its own region is patched. After HMR operations the popstate event is dispatched to nudge SPA routers.

Client API (optional)

Inside any HMR-managed page you can opt into lifecycle hooks — useful for side-effectful top-level code so a hot update does not duplicate its effects:

if (window.htmlBundleHMR) {
  // run cleanup before this unit's changed scripts re-run
  window.htmlBundleHMR.dispose(() => {
    /* e.g. remove nodes this script appended */
  });
  // run after this page has been patched
  window.htmlBundleHMR.accept(() => {
    /* re-init if needed */
  });
  // a plain object that persists across hot updates
  window.htmlBundleHMR.data.rendered = true;
}

import

It is also possible to start the server by importing the package. This could be useful, if you intend to add routes for local development.

import router from "html-bundle";

router.get("/test", (_req, reply) => {
  return reply.send("hi");
});

Optional Config

The CLI flags can also be set by the config. Flags set by the CLI will override the config. Generate the config in the root and call it "bundle.config.js"

src: input path. Default to "src" build: output path. Defaults to "build" port: For the HMR Server. Defaults to 5000. If occupied, the server tries the next available port. The startup URL reports the selected port deletePrev: Whether to delelte the build folder. Defaults to true esbuild: Your additional config html-minifier-terser: Your additional config critical: Your additional config installMissingDependencies: Whether unresolved packages may be installed automatically. Defaults to false licenseNotices: Whether to generate third-party notices. Defaults to false; --licenseNotices enables it regardless of this setting

Example:

/** @type {import('html-bundle').Config} */
export default {
  secure: true,
  handler: "utils/staticFiles.js",
  handlerConcurrency: 4,
  installMissingDependencies: true,
  esbuild: {
    external: ["images"],
  },
};

Third-Party Notices

Notice generation is disabled by default. Enable it with html-bundle --licenseNotices or licenseNotices: true in bundle.config.js. Enabled builds write THIRD-PARTY-NOTICES.txt into the output directory. Deploy this file alongside the generated HTML, JavaScript, CSS, and assets.

The file collects package names, versions, declared license identifiers, and root LICENSE, LICENCE, COPYING, and NOTICE files from esbuild inputs and CSS dependencies reported by PostCSS. Packages are deduplicated across pages and chunks. Esbuild's default legal-comment preservation remains unchanged.

A warning is emitted when a discovered package has no root license file, but only when notice generation is enabled and HMR is off. Missing-license messages remain in the generated file during HMR. This collection is not a compliance guarantee: review those messages, nested or per-file licenses, external/CDN dependencies, fonts, images, copied assets, and CSS imports not reported by PostCSS. Include any additional required notices with the deployment. Dependencies used only as build tools are not collected unless their files are build inputs.

Concept

The bundler always globs files from the src (config) directory. HTML, CSS, and TS/JS are processed into the build (config) directory; unsupported files, including JSON, are copied unchanged by default or passed to the custom handler. JSON imported by inline TS/JS is bundled by esbuild. <script type="importmap"> and <script type="application/ld+json"> blocks are preserved and are not bundled. Server-sent events and hydro-js are used for HMR. In order to trigger SPA Routers, the popstate event is being triggered after HMR Operations.

Example hydro-js

Get the idea from hydro-starter. Set "jsxFactory": "h" in tsconfig.json for JSX.

Input

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Example</title>
    <meta name="Description" content="Example for html-bundle" />
    <script type="module">
      import { render, h, reactive } from "hydro-js";

      function Example({ name }) {
        return <main id="app">Hi {name}</main>;
      }

      const name = reactive("Tester");
      render(<Example name={name} />, "#app");
    </script>
    <style>
      body {
        background-color: whitesmoke;
      }
    </style>
  </head>
  <body>
    <main id="app"></main>
  </body>
</html>

Example Vue.js

Set "jsxFactory": "h" in tsconfig.json.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Vue Example</title>
  </head>
  <script type="module">
    import { createApp, h } from "vue";

    const App = {
      data() {
        return {
          name: "Fabian",
        };
      },
      render() {
        return <p>{this.name}</p>;
      },
    };

    createApp(App).mount("#app");
  </script>
  <body>
    <div id="app"></div>
  </body>
</html>

Example React

Set "jsxFactory": "React.createElement" in tsconfig.json.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>React Example</title>
  </head>
  <script type="module">
    import React, { useState } from "react";
    import { createRoot } from "react-dom/client";

    function Example() {
      const [count, setCount] = useState(0);

      return (
        <div>
          <p>You clicked {count} times</p>
          <button onClick={() => setCount(count + 1)}>Click me</button>
        </div>
      );
    }

    createRoot(document.getElementById("app")).render(<Example />);
  </script>
  <body>
    <div id="app"></div>
  </body>
</html>