Explicit state and event id minification

[benedikt-bartscher]

Summary

Add state and event name minification with CLI management tools.

• Introduces minify.json config file to map state/event names to short IDs (e.g., myapp.state.AppState → "a")
• Adds reflex minify CLI command group for managing minification
• Reduces frontend bundle size and WebSocket payload size by replacing long state/event paths with compact identifiers

CLI Commands

# Initialize minify.json with IDs for all states and events
reflex minify init

# Sync minify.json after code changes
reflex minify sync
reflex minify sync --prune --reassign-deleted

# Validate config against current codebase
reflex minify validate

# List state tree with minified names
reflex minify list
reflex minify list --json

# Lookup a minified path
reflex minify lookup "a.bU"

based on #6098

[codspeed-hq]

Merging this PR will improve performance by 3.08%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
✅ 7 untouched benchmarks

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	test_compile_stateful[_stateful_page]	154.8 µs	150.2 µs	+3.08%

---

_{Comparing benedikt-bartscher:explicit-event-id-minification (e8b5724) with main (7607fa3)}

[abulvenz]

Very tiny optical nit, cause sometimes EventHandlers is the last sub item.
It might work like this, didn't test it.

Suggested change

	console.log(f"{child_prefix}|-- Event Handlers:")
	console.log(f"{child_prefix}{'|' if has_substates else '`'}-- Event Handlers:")

[benedikt-bartscher]

TODO: best-effort-mode

• walk trough the state id registry after the app module get's imported
• filter out all states with explicit state id
• sort the remaining states without state id by full name
• assign state ids - start with the highest user defined state id - users might have fragmentation by choice

a similar thing can be implemented for event handler id's

edit: not that easy, as state names are baked into to many things (events, vars etc). we would need to defer init_subclass and possibly parts of @rx.var and @rx.event

edit2: i have found a better approach with a minify.json which makes this obsolete

[benedikt-bartscher]

Open for discussion: Should reflex reserve the first 5/10 state id's for internal states? Current reflex uses 0-3, but that might change in the future.

edit: with sibling uniqueness we would just need to reserve the state id's on the first rx.State subclass level.

edit2: i have found a better approach with a minify.json which makes this obsolete

[benedikt-bartscher]

TODO: think about sibling uniqueness for states. currently using global uniqueness

edit: adjusted in 6b4c5fa

[benedikt-bartscher]

Idea: store ids in a minify.json file

• allows overwriting state ids for upstream dependencies and reflex core
• one centralized place for the ids
• keep track of reserved numbers
• better automatic instrumentation - state and event ids can all be managed with cli - without manual code changes
• can be loaded once on startup and is frozen - probably faster
• no best effort mode needed

[benedikt-bartscher]

Thanks you @masenf!

the explicit management of the minified names via cli solves our earlier problems of mismatching the minified names between compile and build time, but it seems like a lot of extra api surface area for a mostly under the covers feature.

Yeah, it is. Advanced users and big deployments might prefer managing this manually. I think about it like db migrations. Manual management makes it possible to rename states and event handlers without any issues in production.

would it make sense to auto-minify and store the minify.json as a compilation artifact in the .web/backend directory? we already do something similar to save which pages need to be re-evaluated in backend-only mode in order to have a consistent state tree.

The minify.json should be persisted/commited to have stable id's. However if we decide that minify becomes default, we can certainly auto-update the minify.json during reflex run and/or reflex compile