chore: Optimize WASM builds using Brotli compression

Author: mirkobrombin

cmd/rfw/build/build.go

@@ -9,6 +9,7 @@ import (
 	"path/filepath"
 	"strings"
 
+	"github.com/andybalholm/brotli"
 	"github.com/rfwlab/rfw/cmd/rfw/plugins"
 	_ "github.com/rfwlab/rfw/cmd/rfw/plugins/assets"
 	_ "github.com/rfwlab/rfw/cmd/rfw/plugins/bundler"
@@ -103,6 +104,10 @@ func Build() error {
 		return fmt.Errorf("failed to build project: %s: %w", output, err)
 	}
 
+	if err := compressWasmBrotli(wasmPath); err != nil {
+		return fmt.Errorf("failed to brotli-compress wasm: %w", err)
+	}
+
 	if err := os.MkdirAll(hostDir, 0o755); err != nil {
 		return fmt.Errorf("failed to create host build directory: %w", err)
 	}
@@ -170,3 +175,43 @@ func copyFile(src, dst string) error {
 	}
 	return out.Close()
 }
+
+func compressWasmBrotli(src string) (err error) {
+	in, err := os.Open(src)
+	if err != nil {
+		return err
+	}
+	defer in.Close()
+
+	dst := src + ".br"
+	tmp, err := os.CreateTemp(filepath.Dir(dst), filepath.Base(dst)+".*")
+	if err != nil {
+		return err
+	}
+	tmpName := tmp.Name()
+	defer func() {
+		if tmp != nil {
+			tmp.Close()
+		}
+		if err != nil {
+			_ = os.Remove(tmpName)
+		}
+	}()
+
+	writer := brotli.NewWriterLevel(tmp, brotli.BestCompression)
+	if _, err := io.Copy(writer, in); err != nil {
+		writer.Close()
+		return err
+	}
+	if err := writer.Close(); err != nil {
+		return err
+	}
+	if err := tmp.Close(); err != nil {
+		return err
+	}
+	tmp = nil
+	if err := os.Rename(tmpName, dst); err != nil {
+		return err
+	}
+	return nil
+}

cmd/rfw/build/build_test.go

@@ -1,9 +1,13 @@
 package build
 
 import (
+	"io"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
+
+	"github.com/andybalholm/brotli"
 )
 
 // TestCopyFile ensures copyFile replicates the source file's contents at the
@@ -29,3 +33,32 @@ func TestCopyFile(t *testing.T) {
 		t.Fatalf("expected %q, got %q", content, got)
 	}
 }
+
+func TestCompressWasmBrotli(t *testing.T) {
+	dir := t.TempDir()
+	src := filepath.Join(dir, "app.wasm")
+	content := []byte(strings.Repeat("rfw wasm", 32))
+	if err := os.WriteFile(src, content, 0o644); err != nil {
+		t.Fatalf("write wasm: %v", err)
+	}
+
+	if err := compressWasmBrotli(src); err != nil {
+		t.Fatalf("compressWasmBrotli: %v", err)
+	}
+
+	brPath := src + ".br"
+	f, err := os.Open(brPath)
+	if err != nil {
+		t.Fatalf("open brotli file: %v", err)
+	}
+	defer f.Close()
+
+	reader := brotli.NewReader(f)
+	decompressed, err := io.ReadAll(reader)
+	if err != nil {
+		t.Fatalf("read brotli: %v", err)
+	}
+	if string(decompressed) != string(content) {
+		t.Fatalf("unexpected decompressed content")
+	}
+}

cmd/rfw/initproj/template/wasm_loader.js

@@ -15,33 +15,87 @@
             transition: "width 0.3s ease",
         });
         document.body.appendChild(bar);
+        let interval;
         return {
             start() {
                 let progress = 0;
-                this.interval = setInterval(() => {
+                interval = setInterval(() => {
                     progress = Math.min(progress + Math.random() * 10, 90);
                     bar.style.width = progress + "%";
                 }, 200);
             },
-            finish() {
-                clearInterval(this.interval);
-                bar.style.width = "100%";
-                setTimeout(() => bar.remove(), 300);
+            finish(success = true) {
+                if (interval) {
+                    clearInterval(interval);
+                }
+                if (success) {
+                    bar.style.width = "100%";
+                    setTimeout(() => bar.remove(), 300);
+                } else {
+                    bar.remove();
+                }
             },
         };
     }
+
+    function buildCandidates(url) {
+        const trimmed = url.trim();
+        if (!trimmed) return [];
+        const queryIndex = trimmed.indexOf("?");
+        const base = queryIndex === -1 ? trimmed : trimmed.slice(0, queryIndex);
+        const query = queryIndex === -1 ? "" : trimmed.slice(queryIndex);
+        const candidates = [];
+        if (base.endsWith(".wasm") && !base.endsWith(".wasm.br")) {
+            candidates.push(`${base}.br${query}`);
+        }
+        candidates.push(trimmed);
+        return candidates;
+    }
+
+    async function fetchWithFallback(candidates) {
+        let lastError;
+        for (const candidate of candidates) {
+            try {
+                const resp = await fetch(candidate);
+                if (!resp.ok) {
+                    lastError = new Error(`unexpected status ${resp.status}`);
+                    continue;
+                }
+                return resp;
+            } catch (err) {
+                lastError = err;
+            }
+        }
+        throw lastError || new Error("no wasm candidates provided");
+    }
+
     async function load(url, { go, color, height, blur, skipLoader } = {}) {
+        const candidates = buildCandidates(url);
+        if (candidates.length === 0) {
+            throw new Error("wasm url is empty");
+        }
+
         let bar;
         if (!skipLoader) {
             bar = createBar({ color, height, blur });
             bar.start();
         }
-        const resp = await fetch(url);
-        const bytes = await resp.arrayBuffer();
-        if (bar) bar.finish();
+
+        let response;
+        try {
+            response = await fetchWithFallback(candidates);
+        } catch (err) {
+            if (bar) bar.finish(false);
+            console.error("Failed to load Wasm bundle", candidates, err);
+            throw err;
+        }
+
+        const bytes = await response.arrayBuffer();
+        if (bar) bar.finish(true);
         const result = await WebAssembly.instantiate(bytes, go.importObject);
         go.run(result.instance);
         return result;
     }
+
     global.WasmLoader = { load };
 })(window);

docs/articles/api/wasmloader.md

@@ -6,3 +6,5 @@ Minimal helper for loading WebAssembly modules.
 | --- | --- |
 | `Load(url string, opts Options)` | Fetch and instantiate a WebAssembly module. |
 
+The loader inspects the provided `url` and automatically checks for a Brotli-compressed `.wasm.br` variant before falling back to the original path. Query strings are preserved, so cache-busting patterns like `app.wasm?` work without changes.
+

docs/articles/essentials/creating-application.md

@@ -66,6 +66,8 @@ The compiled `main.go` becomes a WebAssembly bundle. To run it, load the Go runt
 </script>
 ```
 
+The loader automatically looks for `/app.wasm.br` first, preserving cache-busting query strings, and falls back to `/app.wasm` when the compressed asset is unavailable.
+
 > TypeScript support is not yet available. A future release will expose a global `rfw` object to call APIs directly from JavaScript.
 
 ---

docs/articles/getting-started/quick-start.md

@@ -92,7 +92,7 @@ rfw dev --debug
 
 Features:
 
-* Compiles Go sources to `app.wasm`
+* Compiles Go sources to `app.wasm` (served as the Brotli-compressed `app.wasm.br` bundle)
 * Serves static files under `/`
 * Rebuilds and reloads on file changes
 * Runs host components from `host/` if present

docs/articles/guide/cli.md

@@ -66,7 +66,7 @@ Build the project for production. Generates an optimized Wasm bundle and host bi
 
 Artifacts:
 
-* `build/client/` – client bundle
+* `build/client/` – client bundle (`app.wasm` and the Brotli variant `app.wasm.br`)
 * `build/host/` – host binary
 * `build/static/` – copied static files
 

docs/articles/guide/ssc.md

@@ -123,7 +123,7 @@ func main() {
 ## Hydration: how the page becomes interactive
 
 1. The host responds with **fully rendered HTML**.
-2. The browser downloads `app.wasm` and initializes rfw.
+2. The browser downloads the Brotli-compressed `app.wasm.br` (falling back to `app.wasm` when necessary) and initializes rfw.
 3. rfw **hydrates** the server markup: attaches event handlers and reactive bindings.
 4. A WebSocket connects; `h:` values and commands synchronize with the host.
 

docs/articles/guide/wasm-loader.md

@@ -2,6 +2,8 @@
 
 The default project template includes a Go-powered loader that exposes a global `WasmLoader` helper. By default, it shows a red progress bar while the WebAssembly bundle downloads and initializes.
 
+> **Note:** When the build pipeline emits a Brotli-compressed bundle (e.g. `app.wasm.br`), the loader automatically tries the `.wasm.br` asset before falling back to the plain `.wasm` file, so existing calls don’t need to change.
+
 ---
 
 ## Why a Loader?

docs/wasm_loader.js

@@ -15,33 +15,87 @@
             transition: "width 0.3s ease",
         });
         document.body.appendChild(bar);
+        let interval;
         return {
             start() {
                 let progress = 0;
-                this.interval = setInterval(() => {
+                interval = setInterval(() => {
                     progress = Math.min(progress + Math.random() * 10, 90);
                     bar.style.width = progress + "%";
                 }, 200);
             },
-            finish() {
-                clearInterval(this.interval);
-                bar.style.width = "100%";
-                setTimeout(() => bar.remove(), 300);
+            finish(success = true) {
+                if (interval) {
+                    clearInterval(interval);
+                }
+                if (success) {
+                    bar.style.width = "100%";
+                    setTimeout(() => bar.remove(), 300);
+                } else {
+                    bar.remove();
+                }
             },
         };
     }
+
+    function buildCandidates(url) {
+        const trimmed = url.trim();
+        if (!trimmed) return [];
+        const queryIndex = trimmed.indexOf("?");
+        const base = queryIndex === -1 ? trimmed : trimmed.slice(0, queryIndex);
+        const query = queryIndex === -1 ? "" : trimmed.slice(queryIndex);
+        const candidates = [];
+        if (base.endsWith(".wasm") && !base.endsWith(".wasm.br")) {
+            candidates.push(`${base}.br${query}`);
+        }
+        candidates.push(trimmed);
+        return candidates;
+    }
+
+    async function fetchWithFallback(candidates) {
+        let lastError;
+        for (const candidate of candidates) {
+            try {
+                const resp = await fetch(candidate);
+                if (!resp.ok) {
+                    lastError = new Error(`unexpected status ${resp.status}`);
+                    continue;
+                }
+                return resp;
+            } catch (err) {
+                lastError = err;
+            }
+        }
+        throw lastError || new Error("no wasm candidates provided");
+    }
+
     async function load(url, { go, color, height, blur, skipLoader } = {}) {
+        const candidates = buildCandidates(url);
+        if (candidates.length === 0) {
+            throw new Error("wasm url is empty");
+        }
+
         let bar;
         if (!skipLoader) {
             bar = createBar({ color, height, blur });
             bar.start();
         }
-        const resp = await fetch(url);
-        const bytes = await resp.arrayBuffer();
-        if (bar) bar.finish();
+
+        let response;
+        try {
+            response = await fetchWithFallback(candidates);
+        } catch (err) {
+            if (bar) bar.finish(false);
+            console.error("Failed to load Wasm bundle", candidates, err);
+            throw err;
+        }
+
+        const bytes = await response.arrayBuffer();
+        if (bar) bar.finish(true);
         const result = await WebAssembly.instantiate(bytes, go.importObject);
         go.run(result.instance);
         return result;
     }
+
     global.WasmLoader = { load };
 })(window);