feat: pre-compress frontend assets at build time (#6497)

* feat: pre-compress frontend assets at build time

Generate gzip/brotli/zstd sidecars during `reflex export` and serve the
best match via a new PrecompressedStaticFiles handler. Adds a
configurable `frontend_compression_formats` (defaults to gzip) and
switches the prod test harness off the stdlib http.server in favor of
the same Starlette/Uvicorn stack used in production so the precompressed
path is exercised under integration tests.

* assert on content in test_precompressed_staticfiles

---------

Co-authored-by: Masen Furer <m_github@0x26.net>

Author: FarhanAliRaza

packages/reflex-base/src/reflex_base/.templates/web/compress-static.js

@@ -0,0 +1,113 @@
+/* Generate pre-compressed sidecars for the exported static frontend so
+ * production servers can serve them directly without on-the-fly compression. */
+
+import * as zlib from "node:zlib";
+import { join } from "node:path";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
+
+const gzipAsync = promisify(zlib.gzip);
+const brotliAsync =
+  typeof zlib.brotliCompress === "function"
+    ? promisify(zlib.brotliCompress)
+    : null;
+const zstdAsync =
+  typeof zlib.zstdCompress === "function" ? promisify(zlib.zstdCompress) : null;
+
+const COMPRESSIBLE_EXTENSIONS = /\.(js|css|html|json|svg|xml|txt|map|mjs)$/;
+const MIN_SIZE = 256;
+const CONCURRENCY = 16;
+
+const COMPRESSORS = {
+  gzip: {
+    extension: ".gz",
+    compress: (raw) => gzipAsync(raw, { level: 9 }),
+  },
+  brotli: brotliAsync && {
+    extension: ".br",
+    compress: (raw) =>
+      brotliAsync(raw, {
+        params: {
+          [zlib.constants.BROTLI_PARAM_QUALITY]:
+            zlib.constants.BROTLI_MAX_QUALITY,
+        },
+      }),
+  },
+  zstd: zstdAsync && {
+    extension: ".zst",
+    compress: (raw) => zstdAsync(raw),
+  },
+};
+
+const SIDECAR_SUFFIXES = Object.values(COMPRESSORS)
+  .filter(Boolean)
+  .map((c) => c.extension);
+
+async function* walkFiles(directory) {
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const entryPath = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      yield* walkFiles(entryPath);
+    } else if (entry.isFile()) {
+      yield entryPath;
+    }
+  }
+}
+
+function ensureFormatsSupported(formats) {
+  const unavailableFormats = formats.filter(
+    (format) => !COMPRESSORS[format]?.compress,
+  );
+  if (unavailableFormats.length > 0) {
+    throw new Error(
+      `The configured frontend compression formats are not supported by this Node.js runtime: ${unavailableFormats.join(", ")}`,
+    );
+  }
+}
+
+async function compressFile(filePath, formats) {
+  const raw = await readFile(filePath);
+  // Always compress HTML entrypoints so their negotiated sidecars exist.
+  if (raw.length < MIN_SIZE && !filePath.endsWith(".html")) return;
+
+  await Promise.all(
+    formats.map((format) => {
+      const compressor = COMPRESSORS[format];
+      return compressor
+        .compress(raw)
+        .then((compressed) =>
+          writeFile(filePath + compressor.extension, compressed),
+        );
+    }),
+  );
+}
+
+async function compressDirectory(directory, formats) {
+  ensureFormatsSupported(formats);
+
+  const pending = [];
+  for await (const filePath of walkFiles(directory)) {
+    if (
+      COMPRESSIBLE_EXTENSIONS.test(filePath) &&
+      !SIDECAR_SUFFIXES.some((suffix) => filePath.endsWith(suffix))
+    ) {
+      pending.push(filePath);
+    }
+  }
+
+  for (let i = 0; i < pending.length; i += CONCURRENCY) {
+    await Promise.all(
+      pending
+        .slice(i, i + CONCURRENCY)
+        .map((file) => compressFile(file, formats)),
+    );
+  }
+}
+
+const [directory, ...formats] = process.argv.slice(2);
+
+if (!directory) {
+  throw new Error("Missing static output directory for compression.");
+}
+
+await compressDirectory(directory, formats);

packages/reflex-base/src/reflex_base/config.py

@@ -168,6 +168,7 @@ class BaseConfig:
         cors_allowed_origins: Comma separated list of origins that are allowed to connect to the backend API.
         vite_allowed_hosts: Allowed hosts for the Vite dev server. Set to True to allow all hosts, or provide a list of hostnames (e.g. ["myservice.local"]) to allow specific ones. Prevents 403 errors in Docker, Codespaces, reverse proxies, etc.
         react_strict_mode: Whether to use React strict mode.
+        frontend_compression_formats: Pre-compressed frontend asset formats to generate for production builds. Supported values are "gzip", "brotli", and "zstd". Use an empty list to disable build-time pre-compression.
         frontend_packages: Additional frontend packages to install.
         state_manager_mode: Indicate which type of state manager to use.
         redis_lock_expiration: Maximum expiration lock time for redis state manager.
@@ -224,6 +225,11 @@ class BaseConfig:
 
     react_strict_mode: bool = True
 
+    frontend_compression_formats: Annotated[
+        list[str],
+        SequenceOptions(delimiter=",", strip=True),
+    ] = dataclasses.field(default_factory=lambda: ["gzip"])
+
     frontend_packages: list[str] = dataclasses.field(default_factory=list)
 
     state_manager_mode: constants.StateManagerMode = constants.StateManagerMode.DISK
@@ -308,7 +314,7 @@ class Config(BaseConfig):
     - **App Settings**: `app_name`, `loglevel`, `telemetry_enabled`
     - **Server**: `frontend_port`, `backend_port`, `api_url`, `cors_allowed_origins`
     - **Database**: `db_url`, `async_db_url`, `redis_url`
-    - **Frontend**: `frontend_packages`, `react_strict_mode`
+    - **Frontend**: `frontend_packages`, `react_strict_mode`, `frontend_compression_formats`
     - **State Management**: `state_manager_mode`, `state_auto_setters`
     - **Plugins**: `plugins`, `disable_plugins`
 
@@ -348,6 +354,8 @@ def _post_init(self, **kwargs):
         for key, env_value in env_kwargs.items():
             setattr(self, key, env_value)
 
+        self._normalize_frontend_compression_formats()
+
         # Normalize route prefixes to ensure they start with a slash.
         self._normalize_paths()
 
@@ -457,6 +465,29 @@ def _normalize_disable_plugins(self):
                 )
         self.disable_plugins = normalized
 
+    def _normalize_frontend_compression_formats(self):
+        """Normalize and validate configured frontend compression formats.
+
+        Raises:
+            ConfigError: If an unsupported format name is configured.
+        """
+        supported = {"brotli", "gzip", "zstd"}
+        normalized: list[str] = []
+        seen: set[str] = set()
+        for format_name in self.frontend_compression_formats:
+            name = format_name.strip().lower()
+            if not name or name in seen:
+                continue
+            if name not in supported:
+                msg = (
+                    f"frontend_compression_formats contains unsupported format "
+                    f"{format_name!r}. Expected one of: {', '.join(sorted(supported))}."
+                )
+                raise ConfigError(msg)
+            normalized.append(name)
+            seen.add(name)
+        self.frontend_compression_formats = normalized
+
     def _normalize_paths(self):
         """Ensure frontend and backend paths start with a slash if provided."""
         if self.frontend_path and not self.frontend_path.startswith("/"):

reflex/testing.py

@@ -13,7 +13,6 @@
 import re
 import signal
 import socket
-import socketserver
 import subprocess
 import sys
 import textwrap
@@ -22,7 +21,6 @@
 import types
 from collections.abc import Callable, Coroutine, Sequence
 from copy import deepcopy
-from http.server import SimpleHTTPRequestHandler
 from importlib.util import find_spec
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar, Literal, TypeVar
@@ -38,6 +36,7 @@
 import reflex
 import reflex.reflex
 import reflex.utils.build
+import reflex.utils.exec
 import reflex.utils.format
 import reflex.utils.prerequisites
 import reflex.utils.processes
@@ -801,115 +800,28 @@ def expect(
         )
 
 
-class SimpleHTTPRequestHandlerCustomErrors(SimpleHTTPRequestHandler):
-    """SimpleHTTPRequestHandler with custom error page handling."""
-
-    def __init__(self, *args, error_page_map: dict[int, Path], **kwargs):
-        """Initialize the handler.
-
-        Args:
-            error_page_map: map of error code to error page path
-            *args: passed through to superclass
-            **kwargs: passed through to superclass
-        """
-        self.error_page_map = error_page_map
-        super().__init__(*args, **kwargs)
-
-    def send_error(
-        self, code: int, message: str | None = None, explain: str | None = None
-    ) -> None:
-        """Send the error page for the given error code.
-
-        If the code matches a custom error page, then message and explain are
-        ignored.
-
-        Args:
-            code: the error code
-            message: the error message
-            explain: the error explanation
-        """
-        error_page = self.error_page_map.get(code)
-        if error_page:
-            self.send_response(code, message)
-            self.send_header("Connection", "close")
-            body = error_page.read_bytes()
-            self.send_header("Content-Type", self.error_content_type)
-            self.send_header("Content-Length", str(len(body)))
-            self.end_headers()
-            self.wfile.write(body)
-        else:
-            super().send_error(code, message, explain)
-
-
-class Subdir404TCPServer(socketserver.TCPServer):
-    """TCPServer for SimpleHTTPRequestHandlerCustomErrors that serves from a subdir."""
-
-    def __init__(
-        self,
-        *args,
-        root: Path,
-        error_page_map: dict[int, Path] | None,
-        **kwargs,
-    ):
-        """Initialize the server.
-
-        Args:
-            root: the root directory to serve from
-            error_page_map: map of error code to error page path
-            *args: passed through to superclass
-            **kwargs: passed through to superclass
-        """
-        self.root = root
-        self.error_page_map = error_page_map or {}
-        super().__init__(*args, **kwargs)
-
-    def finish_request(self, request: socket.socket, client_address: tuple[str, int]):
-        """Finish one request by instantiating RequestHandlerClass.
-
-        Args:
-            request: the requesting socket
-            client_address: (host, port) referring to the client's address.
-        """
-        self.RequestHandlerClass(
-            request,
-            client_address,
-            self,
-            directory=str(self.root),  # pyright: ignore [reportCallIssue]
-            error_page_map=self.error_page_map,  # pyright: ignore [reportCallIssue]
-        )
-
-
 class AppHarnessProd(AppHarness):
     """AppHarnessProd executes a reflex app in-process for testing.
 
     In prod mode, instead of running `react-router dev` the app is exported as static
-    files and served via the builtin python http.server with custom 404 redirect
-    handling. Additionally, the backend runs in multi-worker mode.
+    files and served via Starlette StaticFiles in a dedicated Uvicorn server.
+    Additionally, the backend runs in multi-worker mode.
     """
 
     frontend_thread: threading.Thread | None = None
-    frontend_server: Subdir404TCPServer | None = None
+    frontend_server: uvicorn.Server | None = None
 
     def _run_frontend(self):
-        web_root = (
-            self.app_path
-            / reflex.utils.prerequisites.get_web_dir()
-            / reflex.constants.Dirs.STATIC
+        with chdir(self.app_path):
+            frontend_app = reflex.utils.exec._frontend_prod_app()
+        self.frontend_server = uvicorn.Server(
+            uvicorn.Config(
+                app=frontend_app,
+                host="127.0.0.1",
+                port=0,
+            )
         )
-        config = reflex.config.get_config()
-        with Subdir404TCPServer(
-            ("", 0),
-            SimpleHTTPRequestHandlerCustomErrors,
-            root=web_root,
-            error_page_map={
-                404: web_root / config.prepend_frontend_path("/404.html").lstrip("/"),
-            },
-        ) as self.frontend_server:
-            frontend_path = config.frontend_path.strip("/")
-            self.frontend_url = "http://localhost:{1}".format(
-                *self.frontend_server.socket.getsockname()
-            ) + (f"/{frontend_path}/" if frontend_path else "/")
-            self.frontend_server.serve_forever()
+        self.frontend_server.run()
 
     def _start_frontend(self):
         # Set up the frontend.
@@ -942,10 +854,26 @@ def _start_frontend(self):
         self.frontend_thread.start()
 
     def _wait_frontend(self):
-        self._poll_for(lambda: self.frontend_server is not None)
-        if self.frontend_server is None or not self.frontend_server.socket.fileno():
+        self._poll_for(
+            lambda: (
+                self.frontend_server is not None
+                and getattr(self.frontend_server, "servers", [])
+                and self.frontend_server.servers[0].sockets
+            )
+        )
+        if (
+            self.frontend_server is None
+            or not self.frontend_server.servers[0].sockets
+            or not self.frontend_server.servers[0].sockets[0].fileno()
+        ):
             msg = "Frontend did not start"
             raise RuntimeError(msg)
+        frontend_socket = self.frontend_server.servers[0].sockets[0]
+        config = get_config()
+        self.frontend_url = "http://{}:{}".format(
+            *frontend_socket.getsockname()
+        ) + config.prepend_frontend_path("/")
+        config.deploy_url = self.frontend_url
 
     def _start_backend(self):
         if self.app_asgi is None:
@@ -982,9 +910,9 @@ def _poll_for_servers(self, timeout: TimeoutType = None) -> socket.socket:
             environment.REFLEX_SKIP_COMPILE.set(None)
 
     def stop(self):
-        """Stop the frontend python webserver."""
-        super().stop()
+        """Stop the frontend and backend servers."""
         if self.frontend_server is not None:
-            self.frontend_server.shutdown()
+            self.frontend_server.should_exit = True
+        super().stop()
         if self.frontend_thread is not None:
             self.frontend_thread.join()