Publish refs as a global for 0.10 compatibility
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)) andaligned_grids(HIGH; fixed in rxe as well, see the linked PR). - a custom component whose
add_hooksstring readsrefs[...]; - a raw
rx.Var("() => refs[...]").to(FunctionVar)handler, andrx.call_functionon 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.jspublishes the registry as a global:globalThis.refs = refs. An unboundrefs[...]in anadd_hooksstring, a rawVarhandler orrx.call_functionresolves to the global, in every module and with anyauto_memoizesetting. A module that binds its ownrefs(animport { refs }or aconst refsinadd_custom_code) shadows the global. It does not conflict with it. -
No implicit
refsimport is added to page or memo modules. An earlier head of this PR importedrefsinto every page and memo module. That broke code that declares its ownrefs: the duplicate binding is a parse error. In dev, React Router parses every route module, so one suchimportreturned HTTP 500 for every route.reflex exportfailed. Oneconst refsin a module also broke unrelated pages whose auto-memo wrappers mirror into the sameapp_componentsmodule. -
refsis declared internal. Thestate.jscomment,docs/wrapping-react/custom-code-and-hooks.mdand the changelog say thatrefsis 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 privateVar._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 onrefsbeing internal.packages/reflex-base/news/+deploy-url-default.breaking.md: now tellsdeploy_urlreaders to useconfig.frontend_url(frontend origin), orconfig.api_urlwhen 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.mdis 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 anid'd input, an auto-memoized button, a component whoseadd_custom_codedeclaresconst refs = {}, and anrx.memothat holds that component. The page module, the legacy_compile_pageoutput and every memo module hold the declaration but import norefs. 2 failed before, 2 pass after.tests/units/components/test_component.py::test_ref_hook_registers_through_state_helperagain expects onlyuseRegisteredRef.- The global itself has no unit test:
tests/jscannot importstate.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.pyand the ref hook test: 94 passed.pre-commit runon the changed files passes: ruff, pyright, ty, biome, update-pyi-files. No component signatures changed, sopyi_hashes.jsonis unchanged.
End to end in a small app, one route per case, driven in Chromium:
| Case | Earlier head (1b1d7867c) | This head |
|---|---|---|
raw Var handler reading refs['ref_target'] | legacy ok | legacy ok |
add_hooks reading refs[...] without the import | hook ok | hook ok |
hook built from Var._as_ref() | as_ref ok | as_ref ok |
add_custom_code: import { refs } from "$/utils/state" | dev HTTP 500 on every route | renders |
add_custom_code: const refs = {...} (page, page with id, rx.memo) | page fails to load; reflex export exits 1 | renders |
| plain memo / page sharing the memo module above | fails to load | renders |
explicit add_imports({"$/utils/state": ["refs"]}), hook-local const refs = useRef() | renders | renders |
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 readsrefs[...]. A deprecation warning for rawrefs[...]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