fix: restore bundled libraries for backend workers

news/7096.bugfix.md

@@ -0,0 +1 @@
+Persist bundled-library metadata for backend-only workers so state hydration can serialize values that reference libraries included in the frontend build.

packages/reflex-base/news/7096.bugfix.md

@@ -0,0 +1 @@
+Persist the bundled-library registry used by backend-only workers when serializing state hydration data.

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

@@ -56,6 +56,8 @@ class Dirs(SimpleNamespace):
     APP_COMPONENTS = "app_components"
     # The name of the env json file.
     ENV_JSON = "env.json"
+    # The name of the compiled bundled-library registry.
+    BUNDLED_LIBRARIES = "bundled_libraries.json"
     # The name of the reflex json file.
     REFLEX_JSON = "reflex.json"
     # The name of the postcss config file.

reflex/compiler/compiler.py

@@ -1241,6 +1241,7 @@ def compile_app(
                 logger.debug(f"BE Evaluating stateful page: {route}")
                 app._compile_page(route, save_page=False)
         if app._state is not None:
+            utils._restore_bundled_libraries()
             utils._compile_initial_state(app._state)
         app._add_optional_endpoints()
         return False
@@ -1261,6 +1262,7 @@ def compile_app(
 
         app._write_stateful_pages_marker()
         if app._state is not None:
+            utils._restore_bundled_libraries()
             utils._compile_initial_state(app._state)
         app._add_optional_endpoints()
         return False
@@ -1463,13 +1465,14 @@ def add_save_task(
             compile_results.append(result)
         progress.advance(task)
 
-    compile_results.append(
+    compile_results.extend([
         compile_contexts(
             app._state,
             radix_themes_plugin.get_theme(),
             component_imports=all_imports,
-        )
-    )
+        ),
+        utils._compile_bundled_libraries(),
+    ])
     progress.advance(task)
 
     compile_results.append(compile_app_root(app_root, hydrate_fallback_export))

reflex/compiler/utils.py

@@ -273,6 +273,32 @@ def serialize_initial_value(value: Any) -> Any:
     )
 
 
+def _compile_bundled_libraries() -> tuple[str, str]:
+    """Return the bundled-library registry as a frontend build artifact.
+
+    Returns:
+        The output path and serialized registry.
+    """
+    bundled_libraries = RegistrationContext.ensure_context().bundled_libraries
+    return constants.Dirs.BUNDLED_LIBRARIES, format.json_dumps(bundled_libraries)
+
+
+def _restore_bundled_libraries() -> None:
+    """Restore the registry emitted by the most recent frontend compile."""
+    path = get_web_dir() / constants.Dirs.BUNDLED_LIBRARIES
+    try:
+        bundled_libraries = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return
+    if not isinstance(bundled_libraries, list) or not all(
+        isinstance(library, str) for library in bundled_libraries
+    ):
+        return
+    RegistrationContext.ensure_context().bundled_libraries[:] = list(
+        dict.fromkeys(bundled_libraries)
+    )
+
+
 def _compile_client_storage_field(
     field: Field,
 ) -> (

tests/units/compiler/test_compiler_utils.py

@@ -3,10 +3,12 @@
 import asyncio
 
 import pytest
+from reflex_base.registry import RegistrationContext
 from reflex_components_core.base.fragment import Fragment
 from reflex_components_core.base.script import Script
 from reflex_components_core.el.elements.metadata import Link
 
+from reflex.compiler import utils
 from reflex.compiler.utils import compile_state, create_document_root
 from reflex.compiler.utils import write_file as compiler_write_file
 from reflex.constants.state import FIELD_MARKER
@@ -20,6 +22,28 @@ def test_write_file_reexport() -> None:
     assert compiler_write_file is write_file
 
 
+def test_bundled_libraries_artifact_round_trip(
+    tmp_path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Backend-only workers can restore the registry from the frontend build."""
+    monkeypatch.setattr(utils, "get_web_dir", lambda: tmp_path)
+    with RegistrationContext() as context:
+        context.bundled_libraries.append("@radix-ui/themes")
+        output_path, output = utils._compile_bundled_libraries()
+        (tmp_path / output_path).write_text(output, encoding="utf-8")
+        context.bundled_libraries[:] = ["react"]
+
+        utils._restore_bundled_libraries()
+
+        assert context.bundled_libraries == [
+            "react",
+            "@emotion/react",
+            "$/utils/context",
+            "$/utils/state",
+            "@radix-ui/themes",
+        ]
+
+
 def test_document_preloads_the_global_stylesheet():
     """Render-blocking CSS should be discoverable alongside early resource hints."""
     head = create_document_root().children[0]