Repository navigation
Publish refs as a global for 0.10 compatibility - #7806
Conversation
Code that reads `refs[...]` without declaring the import (a raw Var event handler, `rx.call_function` on a JS Var, a custom component's `add_hooks` string, and reflex-enterprise's AG Grid API vars) worked on 0.10.1 because `Component._get_hooks_imports` imported `refs` into every module with an id'd component. #7694 replaced that hook with `useRegisteredRef` and dropped the import, so these now throw `ReferenceError: refs is not defined`. Restore the import next to `useRegisteredRef`, and add it to the base imports of every page and memo module, so the add_hooks case also works where the hook lands in a wrapper with no id'd component (auto_memoize=False). An unused or read-only import has no React Compiler cost; only the render-time write that #7694 moved did. Declare `refs` internal in the state.js export comment, the wrapping-react hooks docs and the changelog: components should reference a ref with `Var._as_ref()`, whose var data carries the import. Also tell readers of `config.deploy_url` that it can now be None (FINDING-002). FINDING-003 / FINDING-002 from the reflex 0.11.0a1 pre-release testing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
|
Companion reflex-enterprise PR: https://github.com/reflex-dev/reflex-enterprise/pull/290. It fixes MCP prod startup without 🤖 Generated with Claude Code https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi Generated by Claude Code |
[Medium impact] The PR appears safe to merge; no actionable new issue was found. SummaryThe PR restores access to
Reviews (4) · Last reviewed commit: "fix: publish refs as a global instead of..." · Reviewed by Greptile |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
There was a problem hiding this comment.
All reported issues were addressed across 9 files
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
Merging this PR will degrade performance by 3.11%2 warnings
Warning Please fix the performance issues or acknowledge them on CodSpeed. Performance Changes
Tip Investigate this regression by commenting Comparing |
`_compile_single_memo_function` built its imports from the function's own imports only, so a raw-Var function memo body reading `refs[...]` without declaring the import still threw in an unmirrored (one file per memo) module. Merge `_MEMO_BASE_IMPORTS` there as well, so every memo module imports `refs`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
|
CodSpeed is red here, but this PR doesn't cause it:
CodSpeed flags all three as measured on different hardware for base and head. The event-burst one shows the same 4–5% drop on every PR in this batch. This PR only adds Generated by Claude Code |
The implicit `refs` import in every page and memo module collided with
custom code that binds its own `refs` (a module-level `const refs` or an
explicit `import { refs }` in add_custom_code). The duplicate binding is a
parse error: dev returned HTTP 500 for every route, and `reflex export`
failed. One such component also broke unrelated pages whose auto-memo
wrappers share its mirrored module.
state.js now sets `globalThis.refs = refs`. An unbound `refs[...]` in a
hook string or raw Var resolves to the global, and a module's own `refs`
shadows it. The per-module import shim in the compiler and the ref hook is
removed.
The docs and news no longer point users at the private `Var._as_ref()`;
they name the public event actions instead.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
There was a problem hiding this comment.
1 issue found across 8 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="packages/reflex-base/src/reflex_base/.templates/web/utils/state.js">
<violation number="1" location="packages/reflex-base/src/reflex_base/.templates/web/utils/state.js:71">
P2: This unconditionally overwrites the host page's `globalThis.refs`, so embedded or multiple-frontend deployments can lose an existing registry or resolve compatibility hooks against another app's refs. Publish the compatibility binding through a collision-safe, app-scoped mechanism instead of taking the generic global name.</violation>
</file>
Reply with feedback, questions, or to request a fix.
View guided diff | Turn on auto-fix | Re-trigger cubic
| // code written against 0.10 that reads `refs[...]` without the import keeps | ||
| // working; a module that binds its own `refs` shadows the global. | ||
| export const refs = {}; | ||
| globalThis.refs = refs; |
There was a problem hiding this comment.
P2: This unconditionally overwrites the host page's globalThis.refs, so embedded or multiple-frontend deployments can lose an existing registry or resolve compatibility hooks against another app's refs. Publish the compatibility binding through a collision-safe, app-scoped mechanism instead of taking the generic global name.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/reflex-base/src/reflex_base/.templates/web/utils/state.js, line 71:
<comment>This unconditionally overwrites the host page's `globalThis.refs`, so embedded or multiple-frontend deployments can lose an existing registry or resolve compatibility hooks against another app's refs. Publish the compatibility binding through a collision-safe, app-scoped mechanism instead of taking the generic global name.</comment>
<file context>
@@ -63,11 +63,12 @@ const TOKEN_KEY = "token";
+// code written against 0.10 that reads `refs[...]` without the import keeps
+// working; a module that binds its own `refs` shadows the global.
export const refs = {};
+globalThis.refs = refs;
/**
</file context>
There was a problem hiding this comment.
Not changing this. The global exists only so 0.10-era code that reads the bare identifier refs[...] resolves. A collision-safe or app-scoped name such as globalThis.__reflex_refs would not be found by that code, so the shim would no longer do its job.
As for collisions:
- An iframe-embedded app has its own
globalThis. - Two Reflex frontends can't share one window anyway: the router, socket and
window.__reflexstate are per window. - A module that binds its own
refsstill shadows the global, which was the reason for this change.
The remaining case is a host page that defines its own window.refs in the same window as a Reflex app. That page would have conflicted with 0.10's generated code too.
Generated by Claude Code
There was a problem hiding this comment.
Correction to my reply above: I was wrong that two Reflex frontends can't share a window. Embed mode (entry.client.embed.js, MOUNT_TARGET) mounts a Reflex app into a host page with a memory router, so two embedded Reflex apps can live in the same window. There, the second app's state.js replaces globalThis.refs, and the first app's 0.10-style code that reads bare refs[...] would resolve against the second app's registry. Framework code isn't affected, since it imports refs through Var._as_ref().
No bare global name can serve two apps in one window. The available options:
globalThis.refs ??= refsstops it from overwriting a host page's ownrefs. With two embedded apps, though, the second app's legacy reads would hit the first app's registry instead.- Accept the limitation and document it: legacy bare
refs[...]works for a single app per window.
This is the reviewer's design call, so I'm leaving the thread open rather than resolving it.
Generated by Claude Code
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
* Import refs into every page and memo module for 0.10 compatibility Code that reads `refs[...]` without declaring the import (a raw Var event handler, `rx.call_function` on a JS Var, a custom component's `add_hooks` string, and reflex-enterprise's AG Grid API vars) worked on 0.10.1 because `Component._get_hooks_imports` imported `refs` into every module with an id'd component. #7694 replaced that hook with `useRegisteredRef` and dropped the import, so these now throw `ReferenceError: refs is not defined`. Restore the import next to `useRegisteredRef`, and add it to the base imports of every page and memo module, so the add_hooks case also works where the hook lands in a wrapper with no id'd component (auto_memoize=False). An unused or read-only import has no React Compiler cost; only the render-time write that Declare `refs` internal in the state.js export comment, the wrapping-react hooks docs and the changelog: components should reference a ref with `Var._as_ref()`, whose var data carries the import. Also tell readers of `config.deploy_url` that it can now be None (FINDING-002). FINDING-003 / FINDING-002 from the reflex 0.11.0a1 pre-release testing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi * Import refs into standalone function memo modules too `_compile_single_memo_function` built its imports from the function's own imports only, so a raw-Var function memo body reading `refs[...]` without declaring the import still threw in an unmirrored (one file per memo) module. Merge `_MEMO_BASE_IMPORTS` there as well, so every memo module imports `refs`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi * fix: publish refs as a global instead of importing it into every module The implicit `refs` import in every page and memo module collided with custom code that binds its own `refs` (a module-level `const refs` or an explicit `import { refs }` in add_custom_code). The duplicate binding is a parse error: dev returned HTTP 500 for every route, and `reflex export` failed. One such component also broke unrelated pages whose auto-memo wrappers share its mirrored module. state.js now sets `globalThis.refs = refs`. An unbound `refs[...]` in a hook string or raw Var resolves to the global, and a module's own `refs` shadows it. The per-module import shim in the compiler and the ref hook is removed. The docs and news no longer point users at the private `Var._as_ref()`; they name the public event actions instead. --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Farhan <www.mfarvirus@gmail.com> (cherry picked from commit 381da0f)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi
* Materialize changelogs for reflex-base@0.11.0a1 (new-prerelease-minor) * Materialize changelogs for reflex-components-code@0.11.0a1, reflex-components-core@0.11.0a1, reflex-components-radix@0.11.0a1 (new-prerelease-minor) * Materialize changelogs for reflex-components-lucide@1.1.2a1, reflex-hosting-cli@0.2.2a1, reflex-otel@0.2.1a1, reflex-release@0.2.2a1 (new-prerelease-patch) * Materialize changelogs for reflex@0.11.0a1 (new-prerelease-minor) * Carry the train's changelog edits for fragments changed after 0.11.0a1 #7818, #7816, #7800, #7806 and #7799 edited news fragments that the 0.11.0a1 materialization had already consumed. On the release train (r/pre-2026.11.11) those edits were folded into the matching 0.11.0a1 CHANGELOG.md entries when the fixes were cherry-picked; this carries the same edits to main, where the fragments are consumed by the materialization commits above. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi * Tidy the 0.11.0a1 changelog sections Dedupe entries that appeared in both reflex and reflex-base (SetVar, @rx.event, rx.client_state, awaitable handlers, foreach hooks, lazy libraries, blocking detection) and in reflex-components-core (foreach over set vars), keeping one entry in the reflex changelog. Merge entries for the same change: deploy_url default with the CORS change, React Compiler with auto_memoize, the reflex run shutdown and --json entries, the backend-var errors, the db page-evaluation fixes, and the Redis cancelled-handler fixes. Drop entries that fix features new in this alpha (blocking-monitor report, array ref names, middleware on awaited handlers, folded into the feature) or describe internals (stable ref names, AdminDashRemovedError), trim implementation narrative, and order each category by user impact. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ESN8DhETqtSLLtGDUeGGwV * Tidy the pending news fragments for the next 0.11 alpha Drop fragments that fix behavior new in 0.11.0a1 (awaitable handler returns and hints, @rx.event stacking, the storage factory check, the alembic env.py and page-evaluation regressions, the refs import, the same-origin proxy check, the auto_memoize warning) and fold what users need from them into the matching 0.11.0a1 changelog entries. Remove the reflex-base copies of fragments duplicated in reflex, the base half of the upload error fix (kept in components-core), the dependency-floor and docstring fragments, and merge the two DeclarativeBase detection fragments. Recast the reflex.model import fix as a performance entry and trim implementation detail from the rest. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ESN8DhETqtSLLtGDUeGGwV * Materialize changelogs for reflex@0.11.0a2, reflex-base@0.11.0a2, reflex-components-core@0.11.0a2 (continued-prerelease) * Materialize the #7855 fragment under reflex-base 0.11.0a2 #7855 (Don't wait in Thread.join(timeout) when draining supervised output) merged to main after 0.11.0a2 was cut. It ships in 0.11.0, so its entry goes into the 0.11.0a2 section, which release-from-prerelease collapses into the final 0.11.0 section, and the fragment is consumed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi * Add the #7855 entry to the reflex-base 0.11.0a2 section The previous commit consumed the fragment but left the changelog edit unstaged; this adds the entry it was meant to carry. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi * Keep main's sibling floors instead of the train's alpha floors The alpha materializations raised the root and reflex-components-core floors to the train's alphas (reflex-components-core >= 0.11.0a1, ...). Those tags live on r/pre-2026.11.11 and are not reachable from main, so main's commits build the siblings as 0.10.2.devN / 1.1.2.devN, which check-min-deps rejects. Keep main's .dev0 floors; release-from-prerelease lifts each to the earliest published final once that sibling is tagged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Claude <noreply@anthropic.com>
All Submissions:
Type of change
Changes To Core Features:
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-3921g3of 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_importsimportedrefsfrom$/utils/stateinto every module that had anid'd component, because the old ref hook wroterefs['ref_x'] = ref_xduring render. #7694 replaced that hook withuseRegisteredRefand now imports only that. Any code that readsrefs[...]without declaring the import throws on 0.11.0a1, in dev and prod and in everyauto_memoize×react_compilercell. Affected code:grid.api.*,AgGridAPI.create(id)) andaligned_grids(HIGH; fixed in rxe as well, see the linked PR).add_hooksstring readsrefs[...];rx.Var("() => refs[...]").to(FunctionVar)handler, andrx.call_functionon such a Var.FINDING-002 (reflex side):
deploy_urlnow defaults toNone. The breaking-change fragment never told code that readsconfig.deploy_urlwhat 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 (Accept the backend's own origin behind a TLS-terminating proxy #7799 is editing it).React Compiler: generated modules do not import or write
refsduring render, so the compiler sees no new code. A prod run withreact_compiler=Truepasses 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 (1b1d786), which imported
refsinto 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.tests/jscannot importstate.js, because its runtime dependencies are not installed there. The live app below covers it.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:
Varhandler readingrefs['ref_target']legacy oklegacy okadd_hooksreadingrefs[...]without the importhook okhook okVar._as_ref()as_ref okas_ref okadd_custom_code:import { refs } from "$/utils/state"add_custom_code:const refs = {...}(page, page withid,rx.memo)reflex exportexits 1add_imports({"$/utils/state": ["refs"]}), hook-localconst refs = useRef()Dev (default config) and
--env prodwithreact_compiler=Trueboth pass on this head. On 2d71015 (main before this PR) the rawVarhandler fails withrefs is not defined.Notes
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.Generated by Claude Code