reflex-django

Keep Django. Get a reactive UI in Python. Same process, same port, same cookies.

Documentation · GitHub · PyPI

---

What is it?

You love Django — the ORM, the admin, migrations, the way it just works. You also want a modern, reactive UI written in Python, not React.

reflex-django runs Django and Reflex as one ASGI app on one port. Configuration lives in urls.py. Pages live in views.py. The Django session you got from /admin/login/ is the same session your Reflex button handlers see.

• Same port — Django at 8000, Reflex at 8000. No CORS, no token bridge, no second dev server.
• Same cookies — log in once at /admin/, every Reflex event sees self.request.user.
• Same middleware — your full settings.MIDDLEWARE chain runs on every Reflex event.
• One command — python manage.py run_reflex.

---

Minimal setup

Install:

uv add django reflex reflex-django

config/settings.py:

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "reflex_django",
    "shop",
]

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
    "reflex_django.streaming_middleware.AsyncStreamingMiddleware",
]

config/urls.py:

from django.contrib import admin
from django.urls import path
from reflex_django.urls import reflex_mount

urlpatterns = [path("admin/", admin.site.urls)]
urlpatterns += [
    reflex_mount(app_name="shop", django_prefix=("/admin",)),
]

config/asgi.py:

import os
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
from reflex_django.asgi_entry import application  # noqa: E402,F401

shop/views.py:

import reflex as rx
from reflex_django import template
from reflex_django.state import AppState


class HomeState(AppState):
    @rx.event
    async def on_load(self):
        user = self.request.user
        self.greeting = (
            f"Hi, {user.get_username()}!"
            if user.is_authenticated
            else "Hello, guest. Log in at /admin/."
        )


@template(route="/", title="Home", on_load=HomeState.on_load)
def index() -> rx.Component:
    return rx.vstack(
        rx.heading("My Shop"),
        rx.text(HomeState.greeting),
    )

Run:

python manage.py migrate
python manage.py run_reflex

Open http://localhost:8000/. Admin at http://localhost:8000/admin/.

That's it.

---

Why it exists

Reflex sends UI events over a WebSocket on /_event. Django middleware doesn't run on WebSockets. So request.user, sessions, messages, and CSRF aren't available inside @rx.event handlers by default — and the SPA usually wants its own port, which breaks cookie sharing.

reflex-django builds a synthetic HttpRequest for every event, runs your full settings.MIDDLEWARE chain on it, and binds self.request, self.user, self.session, self.messages, self.csrf_token onto your AppState handler. One process. One port. Same auth as your admin.

Full explanation: Why reflex-django exists.

---

Three files, three jobs

File	What you configure
settings.py	INSTALLED_APPS, MIDDLEWARE (incl. AsyncStreamingMiddleware), REFLEX_DJANGO_*
urls.py	reflex_mount(app_name=..., django_prefix=..., rx_config={...})
{app}/views.py	@template-decorated pages and AppState subclasses

No rxconfig.py. No {app}/{app}.py. No separate frontend.

---

Versions

	Version
Python	3.12+
Django	6.0+
Reflex	0.9.2+

---

Documentation

The full docs walk you through the why, the how, and every knob:

• Why reflex-django exists — the one-page story
• How Django works in 5 minutes
• How Reflex works in 5 minutes
• How the two fit together
• Your first app — a 15-minute todo list
• Add to an existing Django project

Site: https://web7ai.github.io/reflex-django/

---

Common commands

python manage.py run_reflex            # dev server (auto-rebuild + watch)
python manage.py run_reflex --skip-rebuild   # faster reloads for pure Python edits
python manage.py export_reflex         # build the SPA bundle (for CI / deploy)
python manage.py migrate
python manage.py createsuperuser

---

Author: Mohannad Irshedat · GitHub · Docs