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.
- 🦾 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
$ npm install -D html-bundleAdd 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--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.
--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.
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.
- 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.
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.
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;
}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");
});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
deletePrev: Whether to delelte the build folder. Defaults to true
esbuild: Your additional config
html-minifier-terser: Your additional config
critical: Your additional config
Example:
/** @type {import('html-bundle').Config} */
export default {
secure: true,
handler: "utils/staticFiles.js",
handlerConcurrency: 4,
esbuild: {
external: ["images"],
},
};The bundler always globs all HTML, CSS and TS/JS files from the src (config) directory and processes them to the build (config) directory. PostCSS is being used for CSS files and inline styles, html-minifier-terser for HTML and esbuild to bundle, minify, etc. for inline and referenced TS/JS. 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.
Get the idea from hydro-starter.
Set "jsxFactory": "h" in tsconfig.json for JSX.
<!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>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>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>