Integration¶

Get reflex-django running in a Django project. When you finish this page you can open http://localhost:3000/ and see your Reflex app.

Install¶

uv add django reflex reflex-django

Requirements: Python 3.12+, Django 6.0+, Reflex 0.9.4+.

Project layout¶

myshop/
├── manage.py
├── rxconfig.py
├── config/
│   ├── settings.py
│   ├── urls.py
│   └── asgi.py
└── shop/
    ├── shop.py          # app = rx.App() + app.add_page(...)
    ├── views.py         # components and state (optional)
    └── models.py

app_name in rx.Config must match shop/shop.py when your app is named shop.

rxconfig.py¶

import reflex as rx
from reflex_django.plugins import ReflexDjangoPlugin

config = rx.Config(
    app_name="shop",
    plugins=[
        ReflexDjangoPlugin(
            config={
                "settings_module": "config.settings",
                "profile": "integrated",
            }
        ),
    ],
)

The default integrated profile turns on embed, mount, proxy, and bridge. See Profiles for all presets and override patterns. You will learn each pillar in the next pages. If you later disable bridge or resolve an event to tier none, Django request context is not bound for that event.

Public imports¶

The package root lazily resolves Django-heavy imports so import reflex_django is safe during Django app loading. Common public imports:

from reflex_django import configure_django, create_app, register_admin
from reflex_django.plugins import ReflexDjangoPlugin
from reflex_django.states import AppState, ModelState

Most apps only need ReflexDjangoPlugin in rxconfig.py and AppState/ModelState in page modules. configure_django(), create_app(), and build_django_asgi() are advanced helpers for scripts, tests, app factories, and split ASGI deployment.

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.bridge.streaming.AsyncStreamingMiddleware",
]

Add the usual Django dev defaults (SECRET_KEY, DEBUG, DATABASES, etc.). Put AsyncStreamingMiddleware last in MIDDLEWARE.

urls.py and asgi.py¶

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

urlpatterns = [path("admin/", admin.site.urls)]
# SPA catch-all: automatic when mount.enabled is True (default in plugin)

import os

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")

from django.core.asgi import get_asgi_application

application = get_asgi_application()

urls.py is for Django routes only. SPA routes come from app.add_page in shop/shop.py (or optional @page in shop/views.py). See Pages and state.

App module¶

Create shop/views.py with state and UI:

# shop/views.py — state and UI for app.add_page in shop/shop.py
import reflex as rx
from reflex_django.states import AppState


class HomeState(AppState):
    greeting: str = ""

    @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/."
        )


def index() -> rx.Component:
    return rx.vstack(
        rx.heading("My Shop"),
        rx.text(HomeState.greeting),
    )

Register the page in shop/shop.py:

import reflex as rx
from shop.views import HomeState, index

app = rx.App()
app.add_page(
    index,
    route="/",
    title="Home",
    on_load=HomeState.on_load,
)

See the Tutorial for a full app with AppState and the ORM. For serializers and declarative CRUD, see Serializers and Model state.

Run¶

reflex django migrate
reflex run

Open http://localhost:3000/ for the Reflex UI (hot reload).

Open http://localhost:3000/admin/ or http://localhost:8000/admin/ for Django admin (Django is mounted in the Reflex backend by default).

Starting from an existing project¶

Django project: Add rxconfig.py, shop/shop.py, register reflex_django in settings, keep your models and admin.

Reflex project: Run django-admin startproject config ., register the plugin in your existing rxconfig.py, add settings and urls as above.

Common bumps¶

Symptom	Fix
`ModuleNotFoundError: shop.shop`	Create `shop/shop.py` with `app = rx.App()`
`AppRegistryNotReady`	Import models inside handlers, not at module top
Blank page on first run	Wait for compile to finish, then refresh

More fixes: Troubleshooting.

Next: Profiles