html-bundle 6.3.1 → 6.4.0

package/.github/dependabot.yml

@@ -1,7 +1,7 @@
 version: 2
 updates:
-- package-ecosystem: npm
-  directory: "/"
-  schedule:
-    interval: daily
-  open-pull-requests-limit: 99
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 99

package/README.md

@@ -10,7 +10,7 @@ A (primarily) zero-config bundler for HTML files. The idea is to use HTML as Sin
 
 - 🦾 TypeScript (reference it as .js or write inline TS)
 - 📦 Automatic Package Installation
-- 💨 HMR and automatic reconnect
+- 💨 State-preserving HMR with automatic reconnect and full-reload fallback
 - ⚡ [ESBuild](https://github.com/evanw/esbuild)
 - 🦔 [Critical CSS](https://www.npmjs.com/package/beasties)
 - 🚋 Watcher on PostCSS and Tailwind CSS and TS Config
@@ -45,13 +45,45 @@ $ npm run build
 
 ## CLI
 
-`--hmr`: boots up a static server and enables Hot Module Replacement. **This generates a development build and works best when not triggered from the main index.html**<br>
+`--hmr`: boots up a static server and enables Hot Module Replacement. See [HMR](#hmr) for what is hot-patched in place versus reloaded.<br>
 `--secure`: creates a secure HTTP2 over HTTPS instance. This requires the files `localhost.pem` and `localhost-key.pem` in the root folder. You can generate them with [mkcert](https://github.com/FiloSottile/mkcert) for instance.<br>
 `--isCritical`: uses critical to extract and inline critical-path CSS to HTML.<br>
 `--handler`: path to your custom handler. Here, you can handle all non-supported files. You can get the filename via `process.argv[2]`.
 
+## 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.
+- **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.
+
+### 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:
+
+```js
+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.
+
 ```js
 import router from "html-bundle";
 
@@ -60,7 +92,6 @@ router.get("/test", (_req, reply) => {
 });
 ```
 
-
 ## Optional Config
 
 _The CLI flags can also be set by the config. Flags set by the CLI will override the config._

package/dist/bundle.mjs

@@ -92,6 +92,13 @@ async function build(files, firstRun = true) {
         console.log(`💻 Server listening on http${isSecure ? "s" : ""}://${bundleConfig.host === "::" ? "localhost" : bundleConfig.host}:${bundleConfig.port} and is shared in the local network.`);
         console.log(`⌛ Waiting for file changes ...`);
         const chokidarOptions = { awaitWriteFinish: false };
+        let rebuildQueue = Promise.resolve();
+        const enqueueRebuild = (file) => {
+            rebuildQueue = rebuildQueue
+                .catch(() => undefined)
+                .then(() => rebuild(file));
+            return rebuildQueue;
+        };
         if (postcssFile) {
             const postCSSWatcher = watch(postcssFile, chokidarOptions);
             const tailwindCSSWatcher = watch(postcssFile.replace("postcss", "tailwind"), chokidarOptions); // Assuming that the file ext is the same
@@ -111,7 +118,8 @@ async function build(files, firstRun = true) {
                 return;
             }
             try {
-                await rebuild(file);
+                files.push(file);
+                await enqueueRebuild(file);
             }
             catch { }
             console.log(`⚡ added ${file} to the build`);
@@ -121,7 +129,7 @@ async function build(files, firstRun = true) {
                 return;
             }
             file = String.raw `${file}`.replace(/\\/g, "/");
-            await rebuild(file);
+            await enqueueRebuild(file);
             console.log(`⚡ modified ${file} on the build`);
         });
         watcher.on("unlink", async (file) => {
@@ -129,6 +137,9 @@ async function build(files, firstRun = true) {
                 return;
             }
             file = String.raw `${file}`.replace(/\\/g, "/");
+            const fileIndex = files.indexOf(file);
+            if (fileIndex !== -1)
+                files.splice(fileIndex, 1);
             inlineFiles.delete(file);
             const buildFile = getBuildPath(file)
                 .replace(".ts", ".js")
@@ -141,46 +152,84 @@ async function build(files, firstRun = true) {
                     await rm(bfDir);
             }
             catch { }
+            serverSentEvents?.({ type: "full-reload", file });
             console.log(`⚡ deleted ${file} from the build`);
         });
         async function rebuild(file) {
             // Rebuild all CSS because a change in any file might need to trigger PostCSS zu rebuild(e.g. Tailwind CSS)
             await rebuildCSS(files.filter((file) => file.endsWith(".css")));
-            let html;
+            const htmlFiles = files.filter((f) => f.endsWith(".html"));
             if (file.endsWith(".html")) {
+                const previousHtml = builtHTMLCache.get(file);
                 // To refill the inlineFiles needed to build JS
-                for (const htmlFile of files.filter((file) => file.endsWith(".html"))) {
+                for (const htmlFile of htmlFiles) {
                     await writeInlineScripts(htmlFile);
                 }
                 await minifyCode();
-                for (const file of inlineFiles) {
-                    if (INLINE_BUNDLE_FILE.test(file)) {
-                        inlineFiles.delete(file);
-                        await rm(file);
+                for (const inline of inlineFiles) {
+                    if (INLINE_BUNDLE_FILE.test(inline)) {
+                        inlineFiles.delete(inline);
+                        await rm(inline);
                     }
                 }
-                html = await minifyHTML(file, getBuildPath(file));
+                const html = await minifyHTML(file, getBuildPath(file));
+                serverSentEvents?.({ type: "html", file, html, previousHtml });
             }
             else if (/\.(jsx?|tsx?)$/.test(file)) {
+                // A module change alters the inlined output of whichever page(s) import
+                // it. Rebuild every page, then emit only the pages whose HTML actually
+                // changed; the client diff re-runs just the scripts that differ, so
+                // unrelated pages keep their state.
                 inlineFiles.add(file);
+                for (const htmlFile of htmlFiles) {
+                    await writeInlineScripts(htmlFile);
+                }
                 await minifyCode();
+                for (const inline of inlineFiles) {
+                    if (INLINE_BUNDLE_FILE.test(inline)) {
+                        inlineFiles.delete(inline);
+                        await rm(inline);
+                    }
+                }
+                let didEmit = false;
+                for (const htmlFile of htmlFiles) {
+                    const previousHtml = builtHTMLCache.get(htmlFile);
+                    const html = await minifyHTML(htmlFile, getBuildPath(htmlFile));
+                    if (html !== previousHtml) {
+                        didEmit = true;
+                        serverSentEvents?.({
+                            type: "html",
+                            file: htmlFile,
+                            html,
+                            previousHtml,
+                        });
+                    }
+                }
+                if (!didEmit) {
+                    serverSentEvents?.({ type: "full-reload", file });
+                }
+            }
+            else if (file.endsWith(".css")) {
+                serverSentEvents?.({ type: "css", file });
             }
-            else if (!file.endsWith(".css")) {
+            else {
                 if (handlerFile) {
-                    execFilePromise("node", [handlerFile, file]).then(({ stdout }) => {
+                    try {
+                        const { stdout } = await execFilePromise("node", [
+                            handlerFile,
+                            file,
+                        ]);
                         console.log("📋 Logging Handler: ", String(stdout));
-                    });
+                    }
+                    catch (err) {
+                        console.error(err);
+                    }
                 }
                 else {
                     await fileCopy(file);
                 }
+                serverSentEvents?.({ type: "asset", file });
             }
-            else if (handlerFile) {
-                execFilePromise("node", [handlerFile, file]).then(({ stdout }) => {
-                    console.log("📋 Logging Handler: ", String(stdout));
-                });
-            }
-            serverSentEvents?.({ file, html });
         }
     }
 }
@@ -245,6 +294,7 @@ async function minifyCode() {
     }
 }
 const htmlFilesCache = new Map();
+const builtHTMLCache = new Map();
 async function writeInlineScripts(file) {
     let fileText = await readFile(file, { encoding: "utf-8" });
     let DOM;
@@ -359,6 +409,7 @@ async function minifyHTML(file, buildFile) {
         }
     }
     await writeFile(buildFile, fileText);
+    builtHTMLCache.set(file, fileText);
     return fileText;
 }
 async function rebuildCSS(files, config) {

package/dist/hmr-client.d.ts

@@ -0,0 +1,40 @@
+type HTMLMessage = {
+    type: "html";
+    file: string;
+    html: string;
+    previousHtml?: string;
+};
+type HMRMessage = HTMLMessage | {
+    type: "css";
+    file: string;
+} | {
+    type: "asset";
+    file: string;
+} | {
+    type: "full-reload";
+    file: string;
+};
+type Hub = {
+    currentUnit: string | null;
+    lastHTML: Map<string, string>;
+    register(file: string, id: string, handler: {
+        patch: (message: HTMLMessage) => void;
+    }): void;
+    addAccept(file: string, callback: () => void): void;
+    addDispose(file: string, callback: () => void): void;
+    dataFor(file: string): Record<string, unknown>;
+    dispatch(message: HMRMessage): void;
+};
+type HMRPublicAPI = {
+    accept(callback: () => void): void;
+    dispose(callback: () => void): void;
+    readonly data: Record<string, unknown>;
+};
+declare global {
+    interface Window {
+        isHMR?: boolean;
+        __htmlBundleHMR?: Hub;
+        htmlBundleHMR?: HMRPublicAPI;
+    }
+}
+export {};