Skip to content

ENG-12682 Let React Compiler optimize generated components - #7694

Merged
FarhanAliRaza merged 13 commits into
mainfrom
farhan/react-compiler-generation-revive
Nov 10, 2026
Merged

FarhanAliRaza merged 13 commits into
mainfrom
farhan/react-compiler-generation-revive

Conversation

@FarhanAliRaza

@FarhanAliRaza FarhanAliRaza commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Supersedes #7272. That PR was stacked on #7234 and auto-closed, unmerged, when its base branch was deleted after #7234 merged. This PR replays its changes onto current main: the diff between the base-branch head it last merged (07aa53cb6) and its head (4f3e5dbba). Farhan is the commit author.

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

  • New feature (non-breaking change which adds functionality)
  • This change requires a documentation update (included: docs/advanced_onboarding/configuration.md)

Changes

React Compiler bailed out on most generated pages and memo wrappers because of patterns Reflex emits. This PR changes those patterns. It also adds an auto_memoize option, so an app using react_compiler can let the compiler memoize whole pages instead of Reflex's generated memo wrappers.

Bailout Fix
refs["ref_x"] = ref_x during render ("This value cannot be modified") const ref_x = useRegisteredRef("ref_x"). The hook lives in utils/state.js, outside compiler scope, and keeps the same registry behavior.
useMemo(generateUUID, []) ("Expected the first argument to be an inline function expression") useMemo(() => generateUUID(), [])
useCallback deps list addEvents, ReflexEvent, and unused hook bindings such as setFilesById ("Found extra memoization dependencies") Only bindings the callback references
Capture-free (...args) => addEvents(...) handlers crash function outlining ("Expected temporaries to be promoted") enableFunctionOutlining: false
jsx(type, props, ...children) from Emotion is an unknown function, so compiled pages cannot cache elements moduleTypeProvider describing jsx like JSX syntax: frozen arguments, frozen result

The experimental compiler (0.0.0-experimental-a1856f3-20260507) is required, because 1.0.0 still rejects refs passed to jsx() and optional calls in ternary tests. This is still npm's current experimental tag, and REACT_COMPILER_DEV_DEPENDENCIES is the only pin; @babel/core stays at main's 7.29.7.

auto_memoize=False switches MemoizeStatefulPlugin to scope-only wrapping. App-root memoization (_memoize_app_root) is unchanged.

With auto_memoize=False, MemoizeStatefulPlugin still runs in a scope-only mode: it wraps a component only when the component has a lifecycle event or hooks of its own (_get_hooks, add_hooks), and it keeps snapshot boundaries such as rx.foreach. Such hooks belong to one rendered instance, so they cannot move up into the page function: without a wrapper, a hidden rx.cond branch fired on_mount on page load. Components that only read state get no wrapper, and React Compiler memoizes them in the page.

An on_mount inside rx.foreach that reads the loop variable still crashes, as on main; #7793 fixes that separately (#7791).

react_compiler=True logs a warning, once per process, that the option is experimental.

Conflicts with main and how they were resolved

The patch applied cleanly everywhere except two hunks:

I also checked the memo-compiler changes on main that the patch didn't textually touch: mirrored memo modules, auto-memo keying in memoize.py, and compiler.py. default_page_plugins is still the only place page compilation adds MemoizeStatefulPlugin, so the auto_memoize switch still covers every page path.

Measurements (from the original PR #7272)

Production builds, Chromium, direct state dispatch, 11 alternating rounds × 100 updates. Dashboard page: sidebar, 8 KPI cards, two Recharts charts, tabs with a form and a 10-item list, static cards.

Update Today react_compiler react_compiler + auto_memoize=False
One KPI value 0.87 ms, 171 renders 0.095 ms, 28 renders 0.106 ms, 10 renders
Search input 0.99 ms 0.144 ms 0.163 ms
Chart data 5.90 ms 5.19 ms 5.06 ms
Activity list 0.89 ms 0.33 ms 0.42 ms
Header select 1.06 ms 0.27 ms 0.30 ms

Python compile time with auto-memo off (from #7272):

App Auto-memo on Auto-memo off
Dashboard fixture 200 ms 128 ms
Feature fixture 179 ms 144 ms
Docs site 42.2 s 31.7 s

Testing

  • uv run ruff check ., uv run ruff format ., uv run pyright reflex tests (0 errors), and uv run pre-commit run --all-files all pass. The .pyi hook made no changes.
  • tests/units/compiler, tests/units/reflex_base, test_prerequisites.py, test_config.py, and components/test_component.py: 1943 passed.
  • Full unit suite: 15274 passed. The only failures were the 14 reflex_bench/drivers/test_browser.py tests, because the dev container lacks the Playwright headless-shell binary those tests need. That is unrelated to this diff.
  • Smoke app with react_compiler=True, auto_memoize=False under reflex run --env prod:
    • It compiles and builds, with no memo wrappers generated.
    • The page chunk is compiler-transformed (memo cache sentinels are present).
    • In Chromium, three backend increments, rx.set_focus through useRegisteredRef, and a controlled-input round trip all worked, with no page errors.

Known limits (from #7272)

  • With auto_memoize=False, a page the compiler skips re-renders fully on every state change, about 2× slower than today. The docs say to measure before turning it off.
  • Custom components that inject raw hook JavaScript can still cause bailouts.
  • React Compiler fails with "Maximum call stack size exceeded" on a very large component, about 1000 jsx() elements in one generated function, and skips it without a message. With auto_memoize=False, such a page re-renders fully on each update.

https://claude.ai/code/session_01LwJUCTv3FVWzi1UoUpyMLT


Generated by Claude Code

View guided diff Turn on auto-fix

Replays #7272 onto main. That PR auto-closed when its base branch was
deleted after #7234 merged; its own changes were the diff between the
base-branch head it last merged (07aa53c) and its head (4f3e5db),
covering commits c01f4d4, 755ddba and 4f3e5db.

Change the patterns Reflex emits that made React Compiler bail out:
register refs through a useRegisteredRef hook instead of writing to
refs during render, wrap generateUUID in an inline useMemo callback,
list only referenced bindings as useCallback dependencies, disable
function outlining, and describe Emotion's jsx() to the compiler as
JSX. Pin the experimental compiler, which accepts refs passed to jsx().

Add an auto_memoize config option (default True). False removes
MemoizeStatefulPlugin from page compilation so the compiler memoizes
whole pages; app-root memoization is unchanged.

Conflicts with main: #7586 removed hook positions, so the ref hook no
longer passes VarData(position=INTERNAL); #7435 removed
backend_state_mismatch from state.js, so it stays removed.

Claude-Session: https://claude.ai/code/session_01LwJUCTv3FVWzi1UoUpyMLT
@FarhanAliRaza
FarhanAliRaza requested a review from Alek99 October 29, 2026 16:44
@FarhanAliRaza
FarhanAliRaza requested a review from a team as a code owner October 29, 2026 16:44
@linear-code

linear-code Bot commented Oct 29, 2026

Copy link
Copy Markdown

ENG-12682

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 20 files

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread tests/units/compiler/test_plugins.py Resolved
@greptile-apps

greptile-apps Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; the previous lifecycle finding is fixed.

Summary

This PR makes generated components easier for React Compiler to optimize and adds auto_memoize=False.

  • React Compiler can optimize more of Reflex’s generated components.
  • Apps can let React Compiler memoize whole pages while Reflex keeps hook boundaries.

Reviews (10) · Last reviewed commit: "Keep lifecycle of prop components in a w..." · Reviewed by Greptile

@codspeed

codspeed Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

Merging this PR will degrade performance by 4.62%

2 warnings

⚠️ 9 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

⚠️ 3 benchmarks with a significant change ran on different hardware

Their base and head results were measured on machines with a different CPU, core count or memory, so the changes might not come from the code. Run base and head on the same runner type.

Learn more about Macro Runners

See affected benchmarks

❌ 3 regressed benchmarks
✅ 148 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Benchmark BASE HEAD Efficiency
❌ test_route_matching[10] 50.8 µs 53.5 µs -5.13%
❌ test_var_to_dispatch 93.5 µs 98 µs -4.6%
❌ test_process_event_burst_independent_tokens[1] 2.7 ms 2.8 ms -4.12%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


Comparing farhan/react-compiler-generation-revive (da63fcc) with main (2eecce4)

Open in CodSpeed

@masenf masenf added the on deck PRs lined up to review / merge next label Oct 30, 2026
Export GENERATED_EVENT_CALLBACK from the React Compiler adapter and test it
against the names get_memoized_event_triggers produces, so a rename on either
side fails a test instead of silently restoring compiler bailouts.

Drop the Unicode stale-callback claim from the reflex-base fragment: main never
had that bug. Move inline test imports to module level.
Without dry_run, REFLEX_SKIP_COMPILE or a leftover .web/nocompile file made
compile_app return before building the page plugins, and the test wrote into
the working directory's .web.
@masenf masenf added documentation Improvements or additions to documentation perf Performance-improving changes labels Nov 2, 2026
Preserve client-state scope initialization alongside optional auto-memoization,
retain both frontend helper additions, and keep both sets of regression tests.
Add coverage for local client state with auto-memoization enabled and disabled.
Comment thread reflex/compiler/plugins/builtin.py Resolved
@masenf

masenf commented Nov 5, 2026

Copy link
Copy Markdown
Collaborator

@FarhanAliRaza pushed #7741 to address the playwright test failures when using the new client_state implementation. not sure if it's totally replicating what you originally added the test for though, so have a check

…7741)

test_memo_client_counter hard-coded the JavaScript name a client state
var binds its value to ("Δcounter + 1"). Merging main brought in #6936,
which drops the name of a legacy ClientStateVar created with
global_ref=False and suffixes the emitted identifier with RxClientState,
so the hook now reads `const [cs$0RxClientState, setCs$0] = ...` while
the click handler still read `Δcounter`. That bare identifier resolved
to the button carrying id="Δcounter" through the browser's named
element access, and the counter rendered "[object HTMLButtonElement]1".

Build the increment expression from str(counter.value) instead, with a
{value} placeholder for the direct read and a {source} placeholder for
the eval'd reads, so the test follows whatever identifier Reflex emits.
Use rx.client_state(0) and .set(...) in place of the deprecated
ClientStateVar.create / set_value entry points. rx.client_state rejects
non-ASCII names, so the Unicode case becomes a plain scoped counter;
test_react_compiler_callback_dependencies still covers Unicode bindings
in the Babel dependency prune.


Claude-Session: https://claude.ai/code/session_01ESN8Dfnc4fUrUVcPsqaLGk

Co-authored-by: Claude <noreply@anthropic.com>

@masenf masenf left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Withdrawing my earlier approval: the Greptile comment on default_page_plugins (#7694 (comment)) is a real bug in auto_memoize=False, and the same hoisting breaks rx.foreach outright.

I compiled two pages on this branch with default_page_plugins(auto_memoize=False) and compared against the default:

1. rx.cond + lifecycle triggers (Greptile's case)

rx.cond(State.show, rx.text("hi", on_mount=State.mounted, on_unmount=State.unmounted))

With auto-memo off, the useEffect lands in the page function:

function Component() {
  useEffect(() => {
    addEvents([ReflexEvent("...state.mounted", ...)])();
    return () => { addEvents([ReflexEvent("...state.unmounted", ...)])(); }
  }, []);
  const state = useStateContext("...");
  return jsx(Fragment, {}, state.show_rx_state_ ? jsx(RadixThemesText, {as: "p"}, "hi") : ...);
}

on_mount fires at page load even when show is false, and on_unmount only fires when the page unmounts. With the default, the text is wrapped in its own memo component and the effect tracks the branch. React Compiler can't restore this; it memoizes values, it doesn't introduce component boundaries.

2. rx.foreach + any hook-bearing body: generated JS throws

rx.foreach(State.items, lambda it: rx.text(it, on_mount=State.mounted(it)))
function Component() {
  useEffect(() => {
    addEvents([ReflexEvent("...state.mounted", { ["x"]: it_rx_state_ })])();  // ReferenceError: it_rx_state_ is not defined
  }, []);
  ...
  Array.prototype.map.call(state.items_rx_state_ ?? [], ((it_rx_state_, index) => jsx(RadixThemesText, {...}, it_rx_state_)))
}

The loop variable is referenced at page scope, so the page crashes on load. Anything that emits a hook inside the foreach body hits this: lifecycle triggers, rx.client_state, id-derived refs, custom hooks. Today the Foreach snapshot wrapper keeps those hooks inside the per-item component.

So as implemented, auto_memoize=False means "hoist every hook to page scope", and Reflex has never had a mode where that is correct. The PR's own table also shows react_compiler + auto_memoize=False slower than react_compiler alone in four of five rows; only the render count drops.

Suggested resolution, in order of preference:

  1. Drop auto_memoize from this PR and land the bailout fixes (the actual win) on their own. Revisit the option with a scope-preserving design.
  2. Keep the option but make it scope-preserving rather than off: a MemoizeStatefulPlugin mode whose _should_memoize wraps only Cond/Match/Foreach whose subtree carries hooks or lifecycle triggers, and leaves everything else inline for React Compiler. Needs unit coverage for both cases above and a Playwright case for the cond lifecycle behavior.

Repro for both cases is a ~40-line script building a CompileContext with default_page_plugins(auto_memoize=...) and printing compiled_pages["/p"].output_code; happy to share it or add it as the regression test.


Generated by Claude Code

@masenf masenf added this to the v0.11.1 milestone Nov 10, 2026
Without memo wrappers, on_mount and on_unmount hooks were hoisted to the
page function. A hidden rx.cond branch fired on_mount on page load, and an
rx.foreach item hook read the loop variable outside the loop.

Render the events as a MountEffect element beside the component instead.
Comment thread reflex/compiler/plugins/builtin.py Resolved
Comment thread reflex/compiler/plugins/builtin.py Resolved
An on_mount inside rx.foreach was hoisted to the Foreach memo body, where
the loop variable does not exist, so the page crashed. Run
InlineLifecyclePlugin with auto-memoization on as well, and rewrite a
snapshot subtree before the memoize plugin seals it.
Comment thread reflex/compiler/plugins/builtin.py Resolved

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 5 files (changes from recent commits).

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread reflex/compiler/plugins/builtin.py Resolved
Default apps keep the generated code they have on main. The plugin runs
with react_compiler=True or auto_memoize=False.
The MountEffect element kept one instance across an rx.cond branch switch,
so no lifecycle event fired, and its fragment hid the child from an
as_child parent.

With auto_memoize=False, still wrap a component that has a lifecycle event
or hooks of its own in a memo component. A wrapper has its own identity and
forwards props, and it keeps the hooks in their rx.cond branch.
Comment thread reflex/compiler/plugins/builtin.py Resolved

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 7 files (changes from recent commits).

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread reflex/compiler/plugins/memoize.py Resolved
Comment thread reflex/compiler/plugins/builtin.py Resolved
Brings in #7793, which passes loop variables to the wrappers of rx.foreach
items. With auto_memoize off, an item with a lifecycle event or hooks of its
own now gets its wrapper inside the loop body too.

Claude-Session: https://claude.ai/code/session_01LwJUCVweoEhh1JsZA7emsa
…cstring

- An item's lifecycle hook compiles into a wrapper inside the loop body and
  receives the loop variable when auto_memoize is off.
- default_page_plugins names the snapshot boundary and ALWAYS exceptions.

Claude-Session: https://claude.ai/code/session_01LwJUCVweoEhh1JsZA7emsa
Comment thread reflex/compiler/plugins/memoize.py Resolved
With auto_memoize off, a lifecycle event of a component held in a prop moved
into the page function, so it fired on page load even inside a hidden
rx.cond branch. The scope-only rule now uses _has_instance_hooks, which also
checks components held in props.

Claude-Session: https://claude.ai/code/session_01LwJUCVweoEhh1JsZA7emsa
@FarhanAliRaza
FarhanAliRaza merged commit 2d71015 into main Nov 10, 2026
167 of 168 checks passed
@FarhanAliRaza
FarhanAliRaza deleted the farhan/react-compiler-generation-revive branch November 10, 2026 23:27
FarhanAliRaza pushed a commit that referenced this pull request Nov 11, 2026
The config is built several times per run, and the warning added in #7694
had no once-per-process guard, so `reflex compile` logged it twice and
`reflex run` five times. Guard it with a module flag, the same way the
react_compiler warning is guarded by `_warned_react_compiler`.

Found in the reflex 0.11.0a1 pre-release testing (FINDING-047).


Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi

Co-authored-by: Claude <noreply@anthropic.com>
masenf added a commit that referenced this pull request Nov 11, 2026
The config is built several times per run, and the warning added in #7694
had no once-per-process guard, so `reflex compile` logged it twice and
`reflex run` five times. Guard it with a module flag, the same way the
react_compiler warning is guarded by `_warned_react_compiler`.

Found in the reflex 0.11.0a1 pre-release testing (FINDING-047).

Claude-Session: https://claude.ai/code/session_01Dxjadq3qkhKnqZR2b9WBFi

Co-authored-by: Claude <noreply@anthropic.com>
(cherry picked from commit 682201f)
masenf added a commit that referenced this pull request Nov 11, 2026
* 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
#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

* 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>
masenf added a commit that referenced this pull request Nov 11, 2026
* 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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation on deck PRs lined up to review / merge next perf Performance-improving changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants