Implement client state with useClientState hook

[masenf]

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

Description

This PR implements a new client-side state management system using React's useClientState hook, replacing the previous useState-based approach. The implementation provides:

Key Features

1. Scoped Client State: Named client state vars are global and addressable from the backend; unnamed vars are scoped to the component tree that first uses them, enabling per-item state in loops without naming collisions.

2. Per-Slot Subscriptions: Each state var has its own listener set, so writing one var only re-renders components subscribed to that specific var—not all components using client state.

3. Backend Integration: Global client state vars can be pushed from the backend and retrieved via new wire events (_client_state_set, _client_state_get).

4. Functional Updaters: Setters accept lambdas that are traced at compile time, enabling cs.set(lambda v: v + 1) patterns with proper typing.

5. SSR Isolation: Server-side rendering gets a fresh store per request, preventing state leakage between requests.

Implementation Details

• reflex_base.client_state: Core Python API (ClientStateVar, ClientStateSetter, client_state() factory)
• utils/client_state.js: React runtime with scope chain, slot management, and store access
• ClientStateProvider: App-wrap component that mounts the provider and publishes the store
• ClientStateScope: Scope boundary component for per-item state in loops
• Compiler Integration: Auto-memoization of client state setters, hook/import/app-wrap collection via VarData

Backward Compatibility

The original reflex.experimental.client_state.ClientStateVar API is preserved with a deprecation warning. The new rx.client_state(default, name=...) signature is the recommended path forward.

Testing

• 704 lines of JavaScript unit tests (tests/js/client_state.test.js) covering store slots, subscriptions, SSR isolation, provider lifecycle, and scope behavior
• 646 lines of Python unit tests (tests/units/reflex_base/test_client_state.py) covering hook emission, imports, app wraps, setters, and functional updaters
• 232 lines of Playwright integration tests (tests/integration/tests_playwright/test_client_state.py) covering runtime behavior, backend push/retrieve, and per-item state in loops
• Updated memoization tests to account for loop-item scope handling

Documentation

• Updated docs/wrapping-react/overview.md with new API and scoping examples
• Updated docs/library/dynamic-rendering/foreach.md with per-item state patterns

Checklist

• Tests pass with adequate coverage (unit + integration)
• uv run ruff check . and uv run ruff format . clean
• uv run pyright reflex tests passes
• pyi_hashes.json updated
• Documentation updated
• Deprecation warnings added for old API

https://claude.ai/code/session_017DE4XVgDNtq2i89CMVspJ9

[codspeed-hq]

Merging this PR will degrade performance by 5.82%

❌ 6 regressed benchmarks
✅ 21 untouched benchmarks
⏩ 8 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	Simulation	test_compile_all_artifacts[_stateful_page]	27 ms	29.1 ms	-7.07%
❌	Simulation	test_compile_page_full_context[_stateful_page]	34.6 ms	37 ms	-6.45%
❌	Simulation	test_compile_page[_stateful_page]	30.6 ms	32.7 ms	-6.35%
❌	Simulation	test_evaluate_page[_stateful_page]	4.6 ms	4.8 ms	-5.5%
❌	Simulation	test_evaluate_page_with_hooks[_stateful_page]	4.8 ms	5.1 ms	-5.38%
❌	Simulation	test_get_all_imports[_stateful_page]	543.1 µs	566.5 µs	-4.13%

Tip

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

---

_{Comparing claude/clientstatevar-context-refactor-jv3pig (b9d7a5e) with main (f7c848f)}

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. ↩

[greptile-apps]

Greptile Summary

The PR introduces scoped client-side state with React hooks, backend read/write events, SSR-isolated stores, and compiler support for memoized components and loop scopes.

• Adds the rx.client_state Python API and generated JavaScript runtime.
• Integrates client-state scopes with memoization and foreach.
• Adds JavaScript, Python, and Playwright coverage plus documentation.
• Centralizes the client-state registry key for provider publication and backend event access.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previously reported registry-key duplication is fixed because provider publication and event lookup now use the shared JavaScript constant, while the generated Python expression uses the matching Python constant.

Important Files Changed

Filename	Overview
packages/reflex-base/src/reflex_base/.templates/web/utils/client_state.js	Implements scoped stores, per-slot subscriptions, provider publication, loop values, and the client-state hook.
packages/reflex-base/src/reflex_base/.templates/web/utils/state.js	Uses the shared frontend registry-key constant for backend client-state read and write events.
packages/reflex-base/src/reflex_base/client_state.py	Defines the stable Python client-state API, setters, functional updater tracing, and backend integration.
packages/reflex-base/src/reflex_base/constants/state.py	Provides the Python-side client-state registry-key constant used by generated expressions.
tests/js/client_state.test.js	Covers store behavior and verifies that JavaScript and Python registry-key definitions remain synchronized.
packages/reflex-components-core/src/reflex_components_core/core/foreach.py	Integrates per-item scope and scoped loop values into foreach rendering.

_{Reviews (10): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}

[masenf]

On the CodSpeed compile regression

The regression is real and caused by this PR. I don't think it should block, and here's the accounting.

Every regressed benchmark is [_stateful_page], and that fixture (tests/benchmarks/fixtures.py) is foreach-heavy — _simple_foreach() plus _nested_foreach(). Nothing else regressed.

Mechanism. Foreach used to be a snapshot boundary, which sealed its whole subtree from auto-memoization. It no longer does, so a loop-var consumer becomes its own memo component. Compiling _stateful_page goes from 9 to 13 memo definitions — one extra per loop-var consumer per loop. Each definition costs a body render plus a _compute_memo_tag content hash, and that is where the time goes.

That extra memoization is the fix, not overhead next to it. It's what puts a loop-var consumer in its own component so a hoisted useCallback can still read the item (#3210), and what gives each rendered item its own client-state scope. The old path was cheaper because it did strictly less; there's no version of this fix that keeps the subtree sealed.

It's compile-time only — build and hot reload, not the served app. At runtime the change goes the other way: loop items are now individually memoized, so a list update re-renders the items that changed rather than rebuilding every item's subtree.

Follow-up worth doing separately

Profiling _stateful_page locally, _build_wrapper is ~59% of compile, and inside it _compute_memo_tag is ~30% and _analyze_params ~14%. _analyze_params runs twice per memo definition — create_passthrough_component_memo evaluates the memo body once to compute the tag, then _create_component_definition evaluates it again (its own docstring notes this). Removing that second evaluation would recover most of this regression and speed up every memo in every app, not just foreach ones.

I've deliberately left it out of this PR: it touches the memo tag-stability contract, which decides generated module filenames, and it deserves its own change with its own tests rather than riding along here. Happy to open an issue or pick it up next.

Since the cost is inherent to the fix, this wants an acknowledgement on CodSpeed rather than a code change — I don't have access to do that.

---

Generated by Claude Code

[masenf]

Analyze (python) (CodeQL) failed on 362efa43, and it is not this PR's.

The analysis itself completed — every query was interpreted and the SARIF was written:

Exported results to SARIF (214ms)
...
Uploading results
##[warning]Connect Timeout Error (attempted address: api.github.com:443, timeout: 10000ms)
##[error]Connect Timeout Error (attempted address: api.github.com:443, timeout: 10000ms)
...
CodeQL job status was failure.

It died in the upload step on a network timeout to api.github.com, after analysis had already succeeded — so there are no findings involved and nothing in the diff could cause or fix it. Analyze (actions) on the same commit passed.

I've re-run the failed jobs in that workflow once (run 32881954542). If it fails the same way again I'll treat it as real and dig further rather than re-running a second time.

For the record, the only other red check on this commit is CodSpeed, which I addressed separately above. Everything else that has finished is green, including pre-commit, changelog, and js-unit-tests.

---

Generated by Claude Code

[masenf]

Correcting my earlier comment: I said the double-evaluation in create_passthrough_component_memo was staying out of this PR. Having measured it, I've taken half of it in 70b34c5 — the cheap, output-identical half — and left the risky half out.

I judged this by cProfile call counts rather than wall clock, because wall clock on a dev box is meaningless at this delta (interleaved A/B/A/B/A/B mins overlapped completely: 7.21–8.33 ms against 6.54–8.42 ms). Call counts are exactly reproducible.

Per compile of the _stateful_page benchmark fixture (13 memo wrappers):

	total calls/compile	get_type_hints
before	46,195	26
after	43,348 (−6.2%)	13
also reusing the preview body	41,905 (−9.3%)	13

_create_component_definition goes from 12.8% to 4.8% of compile cumtime. Generated output is byte-identical — page plus all 13 memo modules diffed.

What I did not take, and why: reusing the already-evaluated preview as the definition's body is worth a further −3.1%, but it makes the definition body the same object _compute_memo_tag already rendered, and render can mutate (there is a test covering add_hooks filling derived props). Output was identical on the inputs I tried, which is not proof. Not worth the coupling for a third of the benefit.

Where the cost actually is. Not in either double-evaluation. _compute_memo_tag is ~35% of compile cumtime, and the tottime leader across the whole compile is _update_deterministic_hash — roughly 1,140 recursive calls and 3,000 hashlib updates per compile. Anything that meaningfully closes the remaining gap has to come from there, and it deserves its own change.

So the regression is reduced, not eliminated. The rest still wants either an acknowledgement or a follow-up on the tag hash.

---

Generated by Claude Code

[masenf]

CodSpeed on 70b34c5c confirms the prediction: overall regression 10.04% → 5.53%, and the compile benchmarks roughly halved.

Benchmark	before 70b34c5	after
test_compile_all_artifacts[_stateful_page]	32.2 ms (−16.46%)	28.9 ms (−6.82%)	✅ halved
test_compile_page_full_context[_stateful_page]	40 ms (−13.93%)	36.6 ms (−6.12%)	✅ halved
test_compile_page[_stateful_page]	35.7 ms (−14.76%)	32.4 ms (−6.05%)	✅ halved
test_evaluate_page[_stateful_page]	−5.21%	−5.16%	unchanged
test_evaluate_page_with_hooks[_stateful_page]	−5.03%	−4.82%	unchanged
test_get_all_imports[_stateful_page]	−3.92%	−4.18%	unchanged

The −6.2% I measured in interpreter call counts landed as ~8–9 points of wall-clock recovery on the compile benchmarks, so the deterministic metric tracked the real thing well.

The split in that table is worth reading: only the compile benchmarks moved, because they are the ones that build memo definitions. The three that didn't — page evaluation and import collection — never touch _create_component_definition. Their ~5% is the loop-scope plumbing itself: every loop var now carries VarData with a hook and an import, and each item's subtree gets a provider. That part is the fix, and it isn't going anywhere.

So the remaining 5.53% is roughly: ~6% on compile (the extra memo definitions, of which the tag hash is the dominant cost — see above) and ~5% on evaluation (loop-var VarData). Both are the mechanism that makes #3210 work. Still wants an acknowledgement, but at half the size.

---

Generated by Claude Code