Reflex, the framework for building full-stack web apps in pure Python, released v0.11.0 on 12 November 2026. It is a big step towards 1.0. There are new features, such as awaitable event handlers and client-only state, but there are also several breaking changes that can quietly break a production deployment, especially the new CORS defaults. This guide explains the changes that matter most, shows the code fixes, and gives you a safe upgrade path.
Everything here comes from the official Reflex v0.11.0 release notes.
Before you start
Upgrade on a branch, not on main:
git switch -c upgrade-reflex-0.11
pip install -U "reflex==0.11.0" # or: uv add "reflex==0.11.0"
reflex --version
Then work through the sections below in order. The first one is the change most likely to break a live app.
1. deploy_url and CORS: the change that can break production
Before 0.11, deploy_url defaulted to http://localhost:3000, and the backend allowed any origin. Now:
deploy_urldefaults toNone.- In prod mode, when
deploy_urlis unset, the backend sends no CORS headers, so browsers can’t read cross-origin responses, and Socket.IO accepts same-origin connections only. - When
deploy_urlis set, that origin is allowed in addition to the backend’s own origin.
This is a good security default, but it affects you if your frontend and backend are on different origins: a split deployment, a CDN-served frontend, or a proxy that rewrites the Host header. In those setups, set the frontend URL on the backend:
REFLEX_DEPLOY_URL=https://app.example.com reflex run --env prod --backend-only
Or set it in rxconfig.py:
# rxconfig.py
import reflex as rx
config = rx.Config(
app_name="dashboard",
deploy_url="https://app.example.com",
)
For other layouts, list origins explicitly with cors_allowed_origins:
config = rx.Config(
app_name="dashboard",
deploy_url="https://app.example.com",
cors_allowed_origins=["https://app.example.com", "https://admin.example.com"],
)
Setting cors_allowed_origins=["*"] restores the old allow-all behaviour, but only do that if you understand the risk.
Behind a reverse proxy? X-Forwarded-Host and X-Forwarded-Proto are now trusted only when trusted_proxy_hops is set. If your app sits behind one proxy such as Nginx or a load balancer:
config = rx.Config(
app_name="dashboard",
deploy_url="https://app.example.com",
trusted_proxy_hops=1,
)
When a worker rejects an origin for the first time, it logs a warning naming the setting to change, so check your logs after deploying.
Code that reads config.deploy_url must now handle None. Use the new helpers instead:
from reflex.config import get_config
config = get_config()
frontend_origin = config.frontend_url # deploy_url, or http://localhost:<frontend_port>
backend_api = config.api_url # when the backend serves the frontend itself
2. @rx.event now returns an EventHandler
@rx.event used to return the function you decorated. It now returns an EventHandler. In practice:
- Decorator order matters. Put other decorators below
@rx.event. A decorator stacked above it still works for now, with a deprecation warning, until 1.0. - Don’t decorate plain helpers. A module-level function decorated with
@rx.eventwhose first parameter isn’t a state stays a plain function and warns, so drop the decorator. @rx.eventonstaticmethod/classmethod, or on methods of non-state classes, warns and should be removed.rx.event(OtherState.handler)on a handler already bound to another state now raisesTypeError, so decorate the function instead.
import functools
import reflex as rx
def log_calls(fn):
@functools.wraps(fn)
def wrapper(*args, **kwargs):
print(f"calling {fn.__name__}")
return fn(*args, **kwargs)
return wrapper
class CartState(rx.State):
items: list[str] = []
# Before (deprecated): @log_calls above @rx.event
# After: @rx.event on top, other decorators below it
@rx.event
@log_calls
def add_item(self, name: str):
self.items.append(name)
3. Event handlers are now awaitable
This is the headline feature. Inside one event handler, await State.handler(args) runs another handler immediately on the same locked state and returns its result:
import reflex as rx
class CounterState(rx.State):
total: int = 0
@rx.event
def add(self, amount: int) -> int:
self.total += amount
return self.total
@rx.event
async def add_twice(self, amount: int):
await type(self).add(amount)
total = await type(self).add(amount)
yield rx.toast(f"total is now {total}")
A few rules to remember:
- Return values go to the backend code awaiting the handler. They are not sent to the frontend yet.
- An awaited handler passes through app middleware like a queued event. If a middleware blocks it, the
awaitreturnsNone. - Awaiting a handler outside a client event, such as in an API route outside
app.modify_state, raisesEventHandlerTypeError. self.handler()still calls the plain method, as before.
This removes a common workaround of pulling shared logic into private helper methods just so two handlers could reuse it.
4. Client-only state with rx.client_state
rx.client_state is now part of the public API (it was rx._x.client_state). It holds values that live only in the browser, so updating them doesn’t need a round trip to the backend:
import reflex as rx
query = rx.client_state("", name="query") # named = global
def search_box() -> rx.Component:
return rx.input(
value=query.value,
on_change=query.set,
placeholder="Filter products...",
)
A named var is global: any component can read and write it, and the backend can push and retrieve it. An unnamed var belongs to the outermost page or @rx.memo that uses it. Setting a value re-renders only the components that read it. .set replaces .set_value, which is deprecated, and it accepts a value or a lambda such as count.set(lambda v: v + 1). Names must be ASCII identifiers without $.
Render the var with its value property and update it with set, which you can attach directly to a trigger such as on_change. From an event handler, use retrieve to read it and push to write it (both work for named, global vars).
5. Other breaking changes to check
- Set state vars are now
SetVar. Asetorfrozensetvar no longer behaves like a list in frontend code. Indexing, slicing,map,joinand similar are deprecated, so call.to_array()first:State.tags.to_array()[0]. - Browser storage vars (
rx.Cookie,rx.LocalStorage,rx.SessionStorage) must use a storage value as the default or a storage type annotation. Adefault_factorynow fails at compile time. - The built-in admin dashboard is gone.
rx.AdminDash(...)raises an error that links to the admin dashboard guide, which shows how to mount starlette-admin yourself. app()returns a plain ASGI callable, not a Starlette app. If you calledadd_middleware,routesormounton it, move that code toapi_transformer.- Migrations:
rx.ModelRegistry.register(Base)is now optional, and Reflex migrates everyDeclarativeBasesubclass your app imports. If a base belongs to another database or a library, register the bases that belong todb_urlexplicitly. Severalreflex.modelalembic helpers are deprecated in favour ofalembicandreflex dbcommands.
6. Production behaviour changes
- If a Granian backend worker dies, for example from the OOM killer, it is now replaced instead of stopping the whole server. Set
GRANIAN_RESPAWN_FAILED_WORKERS=falseif a process supervisor should handle restarts. reflex db makemigrationsrefuses to add a NOT NULL column whose only default is a dataclassdefault_factory, instead of writing a migration that fails on a table with rows. Use aserver_default, a literaldefault=, or make the column nullable.- The backend no longer wraps the app in an extra Starlette application, which removes a routing layer from every request.
A safe upgrade checklist
- Upgrade on a branch and run
reflex run. Read every deprecation warning. - Search your code:
grep -rn "deploy_url\|AdminDash\|add_middleware\|set_value" . - Decide your CORS setup: same origin (nothing to do), split deploy (
REFLEX_DEPLOY_URL), or several origins (cors_allowed_origins). Settrusted_proxy_hopsbehind proxies. - Fix decorator order around
@rx.eventand remove it from plain helpers. - Add
.to_array()where you index or map over set vars. - Run
reflex db makemigrationsand review the generated revision before applying it. - Deploy to staging and check the browser console and backend logs for rejected origins.
Takeaway
Reflex 0.11 makes apps safer by default and adds real conveniences like awaitable handlers and client-only state. The CORS change is the one to plan for: if your frontend and backend live on different origins, set deploy_url or cors_allowed_origins before you deploy, and the rest of the upgrade is mostly following warnings.
