Skip to content

Minify state var names and allow installing a name resolver after states exist - #7337

Open
benedikt-bartscher wants to merge 238 commits into
reflex-dev:mainfrom
benedikt-bartscher:late-bound-wire-names
Open

benedikt-bartscher wants to merge 238 commits into
reflex-dev:mainfrom
benedikt-bartscher:late-bound-wire-names

Conversation

@benedikt-bartscher

@benedikt-bartscher benedikt-bartscher commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #6100 — the diff includes its commits until that merges. The changes specific to this PR are in fb6992b and the merges of explicit-event-id-minification that follow it.

What this adds

Var name minification. REFLEX_MINIFY_VARS=1 shortens state var keys on the wire using a new optional vars section in minify.json (still schema version 1; older files load with no vars). A minified key is just its id, so a delta goes from {"a.b": {"items_rx_state_": []}} to {"a.b": {"c": []}}. reflex minify init/sync/validate/list/lookup cover vars, and the scheme digest includes them. Var ids that every JS object already has (constructor, __proto__, …) or that end in _rx_state_ are rejected.

A name resolver can be installed after states exist. RegistrationContext.set_name_resolver rebuilds the Vars every registered state holds. Backend dependency tracking and VarData.field_dependencies now key on classes and the resolver-independent default name, so they never go stale. This lets in-process AppHarness tests run fully minified. A Var built from state Vars before the install (e.g. a module-level component imported before minify.json was loaded) is not fixed; compiling fails with a message naming each stale reference instead of shipping a broken frontend.

One place builds wire keys. format_var_key / format_state_var (which reads through the prefixed local format_state_local from #6100) replace the ad-hoc name + FIELD_MARKER concatenations; update_vars_internal maps keys back through a per-state lookup, and state.js reads the hydrated flag's key from the compiled context instead of hardcoding it.

Notes

  • setvar still sends the Python var name: it dispatches through the class hierarchy, where a per-state id would be ambiguous.
  • REFLEX_PERF_MODE's check for stringified vars keys on the field marker, so it doesn't see minified vars.
  • Router fields and is_hydrated are minified too; nothing in the frontend reads them by name anymore.
  • New public API: NameResolver.resolve_var_name, reflex_base.utils.format.format_var_key / format_state_var.

Testing

  • Unit tests for var ids, config validation, sync/prune, the stale-name check, rebuilding Vars on a late install, dependency tracking and always-dirty substates under renamed states, client-storage compile, update_vars_internal with minified keys, and the CLI.
  • tests/integration/test_minification.py now runs in-process with framework states and vars minified.
  • A downstream app driven by Playwright in prod with all three modes on: inherited, computed and backend vars, background tasks, ComponentState, cookie/localStorage persistence across tabs, dynamic routes; websocket frames carry no var or state names.

🤖 Generated with Claude Code

benedikt-bartscher and others added 30 commits January 24, 2026 20:43
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
When a parent and child state have the same minified name, substate
resolution can fail because the leading segment is stripped incorrectly. This
change adds a flag to skip stripping only on the initial recursive call, ensuring
correct resolution even in name collision scenarios.
The frontend keys its state maps by dotted state path, so only a root's
key is its id alone; a nested state on 'constructor' is keyed
'parent.constructor' and stays valid.
The default state name is snake-cased, so 'cartItem' and 'cart_item'
named the same state and the second create() hit the sibling-shadowing
guard. A key without capitals keeps its spelling in that name.
Log messages wrap to the terminal width, so their output is compared
with the wrapping undone. The validate test configures every other
state, so its output is the one error alone.
# Conflicts:
#	docs/api-reference/minification.md
#	reflex/minify.py
#	tests/units/test_reflex.py
A background task passes its StateProxy as state, so type() gave the proxy
class, which the minify resolver can't place.
'reflex minify validate' decided whether an entry is a root by its recorded
parent alone, so a root whose parent was stale but not null passed on an
id such as 'constructor', which the frontend would key as a bare root. The
app loads the file by the recorded parent and the frontend keys the state by
its actual one, so the id is now checked as a root's when either says root.
The minify tests matched errors, warnings and the stale-config log line by
a fragment, which passes when the rest of the message is wrong. They now
compare each one whole, as does the duplicate component state key test.
try_get went through get() and caught its LookupError. BaseContext.get only
reads the context var, so ContextVar.get(None) gives the same answer without
the extra call and exception: try_get drops from ~49 to 18 ns, which every
event pays several times via format_event_handler.
get_event_handler_parts and format_event_handler imported the registry on
every call. The registry only imports reflex_base.context.base and
reflex_base.utils.exceptions, neither of which imports format, so the import
moves to the module. With the try_get change, _connect_supersedes (every
enqueue) drops from ~340 to ~155 ns and get_hydrate_event (every event) from
~194 to ~106 ns.
set_name_resolver called cache_clear on get_name, get_full_name,
_get_substate_path and get_class_substate for every registered state, but
each is one functools cache shared by all state classes, so the first
class's calls already cleared them. Clear them once.
test_lookup_resolves_minified_path defines AppState and ChildState inside
the test, so they move to reflex.istate.dynamic and take a suffix when a
state of that name already lives there. Run after other tests defining a
local ChildState (e.g. with pytest-randomly, seed 2 over test_reflex,
test_state, test_var and test_minify), the lookup printed ChildState_2 and
the hard-coded expectation failed.
set_name_resolver cleared every name cache and rebuilt the Vars of every
registered state on each install, though most installs change no name:
clear_config_cache() without a minify.json, as the temp_minify_json fixture
calls twice per test, swaps one unminified resolver for another. A built-in
resolver's digest covers every name it gives, so when the outgoing resolver
and the one the shared caches were last rebuilt under (another context may
have installed it) are both built-in with the new one's digest, the new
resolver is only swapped in. Custom resolvers, which may rename under any
digest, still always rebuild.

Over test_state, test_minify and test_reflex: 516 installs ran 235k
_rebuild_vars calls taking 11.6 s; now 57k taking 3.1 s, and the three
files run in 21.5 s instead of 31.8 s.
raise_for_stale_names ran its regexes over all compiled code on every
compile, though code can only hold a stale name if an install changed the
names after one was handed out. set_name_resolver now records that (when it
does not merely swap in a resolver giving the same names, and anything was
issued yet), and the scan returns at once until it happened, e.g. for every
app without a minify.json or with one loaded before any state was created.
Over 8 MB of compiled code: 131 ms -> 0 ms.
raise_for_stale_names rebuilt the list of states going by a local, iterating
its WeakSet and formatting each owner's local, for every read of the local
in the compiled code. The answer cannot change within one scan, so it is
kept per local. Over 8 MB of compiled code the scan, when it runs, takes
84 ms instead of 131 ms.
build_delta and BaseState.dict looked up every var's wire key through the
functools cache of format_var_key. _init_frontend_var_names already
computes those keys, and is rerun when a resolver changes them, so it now
also keeps the forward {name: key} map that both read. A delta of 20
dirty vars builds in ~3.8 instead of ~4.5 us, a dict() of them in ~3.8
instead of ~4.2 us.
It compiled and ran the same app as the enabled mode; only where
minify.json is read from differed, which test_minify_json_path_from_env_var
and test_env_var_pins_the_config_for_every_directory already cover. The
test now runs three modes per harness instead of four.
reflex_base.utils.format imports the registry at the top now, so the import
inside format_var_key is redundant.
Comment on lines +589 to +593
if _same_names(previous, resolver) and _same_names(
_names_built_under, resolver
):
_names_built_under = resolver
return

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.

P1 Restored apps keep wrong names

This shortcut can skip a needed rebuild. Start with state X in context A, let a fork install minified names, then install default names in an unrelated context that does not contain X. That last install sets _names_built_under to default without rebuilding X.

Reinstalling A's default resolver now returns here, leaving X's Vars and _var_keys minified while A uses default names. Compilation can fail or produce state reads that do not match the emitted keys. Track which names each context's classes were built under, rather than trusting the last install anywhere.

…inification

- reflex-dev#7583's field subscription goes on the state's local, which a resolver
  can prefix with `$rx_`; the two hook tests expect the field list.
- reflex-dev#7938's wait for the lost-and-found subscription runs after the per-SID
  setup, which has to happen before the connect's first await, and still
  before link_token_to_sid stores the socket record.
A renamed state's local carries the `$rx_` prefix, which the hook merge's
`\w+` did not match. A component reading two fields of a minified state
kept both hooks, so its compiled code declared the local twice and the
production build failed.
Brings upstream to df7f157 (reflex-dev#7583) and the hook merge fix for `$rx_`
locals. reflex-dev#7583's hook names the state the way the frontend does and lists
each field by format_var_key, the key the resolver gives it in the store;
_var_set_state records the default state name like every other VarData.
A text reading `label` and `count` of the minified root state compiles
both field subscriptions into one hook. Before c99f0e0 the merge
skipped the `$rx_` local, and the build failed with
"Identifier `$rx_reflex___state____state__k` has already been declared".
# Conflicts:
#	tests/integration/test_minification.py

This branch has not been deployed

No deployments
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 enhancement Anything you want improved perf Performance-improving changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants