reflex-django 0.5.0

Run a Django backend (Django ORM, Django Admin) alongside a Reflex app.

reflex-django

Keep Django. Get a reactive UI in Python. One process, shared cookies, native Reflex dev.

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. Reflex config lives in settings.py. Pages live in views.py. The SPA catch-all is automatic. The Django session you got from /admin/login/ is the same session your Reflex button handlers see.

• One process — production on one port; dev runs Vite (:3000) + backend (:8000) via run_reflex. No CORS, no token bridge.
• 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",
]

REFLEX_DJANGO_RX_CONFIG = {
    "app_name": "shop",
    "frontend_port": 3000,
    "backend_port": 8000,
}

config/urls.py:

import shop.views  # noqa: F401 — register @page decorators at import time

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

urlpatterns = [path("admin/", admin.site.urls)]
# catch-all: automatic (REFLEX_DJANGO_AUTO_MOUNT=True)

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.pages.decorators import page
from reflex_django.states 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/."
        )


@page(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

run_reflex starts two dev servers: Vite on :3000 (SPA + hot reload) and Django/Reflex on :8000 (admin, API, /_event).

Open http://localhost:3000/ for your Reflex UI. Admin at http://localhost:8000/admin/ (Vite proxies admin/API paths to :8000).

Optional: python manage.py run_reflex --single-port to browse only http://localhost:8000/.

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 knobs

Knob	Where	What you configure
Settings	settings.py	INSTALLED_APPS, MIDDLEWARE, REFLEX_DJANGO_RX_CONFIG (app_name, ports, redis_url, …)
App	{app}/views.py	@page pages and AppState subclasses (from reflex_django import app for add_page)
URLs	urls.py	Django routes + import shop.views to register pages; catch-all is automatic

No rxconfig.py. No {app}/{app}.py. No required reflex_mount() line. Call reflex_mount() only for URL overrides (mount_prefix, explicit django_prefix).

Full map: The three knobs.

---

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:

• The three knobs (start here) — settings, app, URLs; page registration vs catch-all
• 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
• Local development (Vite, admin CSRF, frontend patches)
• 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