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_url defaults to None.
  • In prod mode, when deploy_url is 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_url is 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.event whose first parameter isn’t a state stays a plain function and warns, so drop the decorator.
  • @rx.event on staticmethod/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 raises TypeError, 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 await returns None.
  • Awaiting a handler outside a client event, such as in an API route outside app.modify_state, raises EventHandlerTypeError.
  • 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. A set or frozenset var no longer behaves like a list in frontend code. Indexing, slicing, map, join and 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. A default_factory now 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 called add_middleware, routes or mount on it, move that code to api_transformer.
  • Migrations: rx.ModelRegistry.register(Base) is now optional, and Reflex migrates every DeclarativeBase subclass your app imports. If a base belongs to another database or a library, register the bases that belong to db_url explicitly. Several reflex.model alembic helpers are deprecated in favour of alembic and reflex db commands.

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=false if a process supervisor should handle restarts.
  • reflex db makemigrations refuses to add a NOT NULL column whose only default is a dataclass default_factory, instead of writing a migration that fails on a table with rows. Use a server_default, a literal default=, 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

  1. Upgrade on a branch and run reflex run. Read every deprecation warning.
  2. Search your code: grep -rn "deploy_url\|AdminDash\|add_middleware\|set_value" .
  3. Decide your CORS setup: same origin (nothing to do), split deploy (REFLEX_DEPLOY_URL), or several origins (cors_allowed_origins). Set trusted_proxy_hops behind proxies.
  4. Fix decorator order around @rx.event and remove it from plain helpers.
  5. Add .to_array() where you index or map over set vars.
  6. Run reflex db makemigrations and review the generated revision before applying it.
  7. 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.