fix: restore bundled libraries for backend workers

[harsh21234i]

Summary

Fix backend-only workers losing bundled-library metadata after the
frontend has already been compiled.

When a backend worker skips frontend compilation, its bundled-library
registry was incomplete. Serializers for values referencing libraries such
as @radix-ui/themes could then raise during state hydration, causing the
entire hydrate delta to be dropped.

Changes

• Persist the final bundled-library registry as .web/ bundled_libraries.json.
• Restore the registry before backend-only initial-state serialization.
• Add a regression test covering registry persistence and restoration.
• Add a bugfix release note.

Testing

• git diff --check passed.
• Isolated Ruff checks passed.
• Focused pytest execution was attempted

Closes #7096

[greptile-apps]

Confidence Score: 5/5

The implementation appears safe to merge, with only the non-blocking lack of direct compiler-wiring regression coverage remaining.

Findings

1.  Compiler Wiring Is Untested ▶

Summary

• Adds a named path constant for the registry artifact.
• Emits the finalized registry during frontend compilation.
• Restores and validates the registry in backend-only compilation paths.
• Adds release notes and helper-level round-trip coverage.

_{Reviews (3) · Last reviewed commit: "style: satisfy pre-commit checks"}

[greptile-apps]

Compiler Wiring Is Untested

This test manually writes the registry artifact and directly calls both helpers. It would still pass if compile_app stopped emitting the artifact or restoring it before initial-state serialization, leaving the orchestration behind this fix without regression coverage.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[cubic-dev-ai]

2 issues found across 5 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="reflex/compiler/compiler.py">

<violation number="1" location="reflex/compiler/compiler.py:1244">
P2: When a backend-only worker discovers a library while evaluating a page, this restore replaces that registration with the older frontend snapshot before initial-state serialization. Restore the snapshot before evaluating pages, or merge it with registrations discovered during evaluation, so page-level `bundle_library()` calls remain available.</violation>
</file>

<file name="reflex/compiler/utils.py">

<violation number="1" location="reflex/compiler/utils.py:291">
P2: When `bundled_libraries.json` contains invalid UTF-8, `read_text()` raises `UnicodeDecodeError` before JSON parsing, so backend-only compilation crashes instead of falling back. Catch `UnicodeDecodeError` here (or the broader `ValueError`) with the existing malformed-file exceptions.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When a backend-only worker discovers a library while evaluating a page, this restore replaces that registration with the older frontend snapshot before initial-state serialization. Restore the snapshot before evaluating pages, or merge it with registrations discovered during evaluation, so page-level bundle_library() calls remain available.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At reflex/compiler/compiler.py, line 1244:

<comment>When a backend-only worker discovers a library while evaluating a page, this restore replaces that registration with the older frontend snapshot before initial-state serialization. Restore the snapshot before evaluating pages, or merge it with registrations discovered during evaluation, so page-level `bundle_library()` calls remain available.</comment>

<file context>
@@ -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()
</file context>

[cubic-dev-ai]

P2: When bundled_libraries.json contains invalid UTF-8, read_text() raises UnicodeDecodeError before JSON parsing, so backend-only compilation crashes instead of falling back. Catch UnicodeDecodeError here (or the broader ValueError) with the existing malformed-file exceptions.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At reflex/compiler/utils.py, line 291:

<comment>When `bundled_libraries.json` contains invalid UTF-8, `read_text()` raises `UnicodeDecodeError` before JSON parsing, so backend-only compilation crashes instead of falling back. Catch `UnicodeDecodeError` here (or the broader `ValueError`) with the existing malformed-file exceptions.</comment>

<file context>
@@ -273,6 +273,32 @@ def serialize_initial_value(value: Any) -> Any:
+    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(
</file context>

Suggested change

	except (OSError, json.JSONDecodeError):
	except (OSError, UnicodeDecodeError, json.JSONDecodeError):

[codspeed-hq]

Merging this PR will not alter performance

✅ 40 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing harsh21234i:fix/7096-noncompiling-bundled-library (bfa4e31) with main (9165dc6)}

Footnotes

1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩