Publish refs as a global for 0.10 compatibility

Merged
MA
10d ago
+84-3

All Submissions:

  • Have you followed the guidelines stated in CONTRIBUTING.md file?
  • Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • This change requires a documentation update

Changes To Core Features:

  • Have you added an explanation of what your changes do and why you'd like us to include them?
  • Have you written new tests for your core changes, as applicable?
  • Have you successfully ran tests with your changes locally?

Release fix-up for FINDING-003 and the reflex half of FINDING-002 from the reflex 0.11.0a1 pre-release testing (artifacts on branch claude/vibrant-pasteur-3921g3 of reflex-dev/reflex, prerelease-testing/runs/2026-11-11-v0.11.0a1/).

Defect

FINDING-003: ReferenceError: refs is not defined. On 0.10.1, Component._get_hooks_imports imported refs from $/utils/state into every module that had an id'd component, because the old ref hook wrote refs['ref_x'] = ref_x during render. #7694 replaced that hook with useRegisteredRef and now imports only that. Any code that reads refs[...] without declaring the import throws on 0.11.0a1, in dev and prod and in every auto_memoize × react_compiler cell. Affected code:

  • reflex-enterprise AG Grid API vars (grid.api.*, AgGridAPI.create(id)) and aligned_grids (HIGH; fixed in rxe as well, see the linked PR).
  • a custom component whose add_hooks string reads refs[...];
  • a raw rx.Var("() => refs[...]").to(FunctionVar) handler, and rx.call_function on such a Var.

FINDING-002 (reflex side): deploy_url now defaults to None. The breaking-change fragment never told code that reads config.deploy_url what to use instead. reflex-enterprise's MCPPlugin died at prod startup because of this.

Fix

  • state.js publishes the registry as a global: globalThis.refs = refs. An unbound refs[...] in an add_hooks string, a raw Var handler or rx.call_function resolves to the global, in every module and with any auto_memoize setting. A module that binds its own refs (an import { refs } or a const refs in add_custom_code) shadows the global. It does not conflict with it.

  • No implicit refs import is added to page or memo modules. An earlier head of this PR imported refs into every page and memo module. That broke code that declares its own refs: the duplicate binding is a parse error. In dev, React Router parses every route module, so one such import returned HTTP 500 for every route. reflex export failed. One const refs in a module also broke unrelated pages whose auto-memo wrappers mirror into the same app_components module.

  • refs is declared internal. The state.js comment, docs/wrapping-react/custom-code-and-hooks.md and the changelog say that refs is an internal implementation detail with no compatibility guarantee. They point users at public event actions (rx.set_value, rx.set_focus, rx.scroll_to), not at the private Var._as_ref(). The global exists only so code written against 0.10 keeps working in 0.11.

  • News fragments:

    • news/+refs-compat-import.misc.md: new.
    • packages/reflex-base/news/+react-compiler-generated-code.feature.md: one added sentence on refs being internal.
    • packages/reflex-base/news/+deploy-url-default.breaking.md: now tells deploy_url readers to use config.frontend_url (frontend origin), or config.api_url when the backend serves the frontend (single-port --env prod).

    Both reflex-base edits correct unreleased 0.11.0a1 fragments on main. news/+cors-prod-default.breaking.md is untouched (#7799 is editing it).

React Compiler: generated modules do not import or write refs during render, so the compiler sees no new code. A prod run with react_compiler=True passes every case below. The _c(n) counts were not measured again after the change to a global.

Test plan

Regression test, written first and failing on the earlier head of this PR (1b1d7867c), which imported refs into every module:

  • tests/units/compiler/test_compiler.py::test_custom_code_may_declare_refs[auto_memoize True|False]: a page with an id'd input, an auto-memoized button, a component whose add_custom_code declares const refs = {}, and an rx.memo that holds that component. The page module, the legacy _compile_page output and every memo module hold the declaration but import no refs. 2 failed before, 2 pass after.
  • tests/units/components/test_component.py::test_ref_hook_registers_through_state_helper again expects only useRegisteredRef.
  • The global itself has no unit test: tests/js cannot import state.js, because its runtime dependencies are not installed there. The live app below covers it.
  • The deploy_url fragment change has no test.

Local results (targeted):

  • tests/units/compiler/test_compiler.py and the ref hook test: 94 passed.
  • pre-commit run on the changed files passes: ruff, pyright, ty, biome, update-pyi-files. No component signatures changed, so pyi_hashes.json is unchanged.

End to end in a small app, one route per case, driven in Chromium:

CaseEarlier head (1b1d7867c)This head
raw Var handler reading refs['ref_target']legacy oklegacy ok
add_hooks reading refs[...] without the importhook okhook ok
hook built from Var._as_ref()as_ref okas_ref ok
add_custom_code: import { refs } from "$/utils/state"dev HTTP 500 on every routerenders
add_custom_code: const refs = {...} (page, page with id, rx.memo)page fails to load; reflex export exits 1renders
plain memo / page sharing the memo module abovefails to loadrenders
explicit add_imports({"$/utils/state": ["refs"]}), hook-local const refs = useRef()rendersrenders

Dev (default config) and --env prod with react_compiler=True both pass on this head. On 2d71015b7 (main before this PR) the raw Var handler fails with refs is not defined.

Notes

  • The compatibility shim is one global in state.js. A later minor can remove it once downstream code no longer reads refs[...]. A deprecation warning for raw refs[...] usage is out of scope here, because the compiler cannot detect such strings cheaply.
  • Companion reflex-enterprise PR (MCP prod startup, MCP consent redirect, AG Grid refs): linked in a comment below.

Generated by Claude Code