reflex-django

Unify the robust backend power of Django and the highly interactive, Python-first reactive UI of Reflex into a single process.

---

Welcome to the official documentation for reflex-django!

This library acts as a bridge that brings Django ASGI and Reflex together in one process started by the single standard command: reflex run.

By combining the strength of Django's robust ecosystem (its ORM, administrative panel, session store, migration framework, and URL routing) with Reflex's fast, modern, reactive user interfaces, you get a premium developer experience. You no longer need to run, configure, and maintain separate backend and frontend development servers.

Whether you are starting a new greenfield application or looking to mount a highly interactive modern web interface onto an existing enterprise Django codebase, reflex-django is built to scale with your architectural needs.

---

Choose your path

🚀 Starting from Scratch

Initialize a new full-stack project combining the power of Django ORM and Reflex reactivity in minutes.

🔌 Existing Django Codebase

Seamlessly mount a modern Reflex frontend onto your existing Django enterprise application.

---

Quick Installation

Get up and running immediately. You can install reflex-django directly from PyPI using your favorite package manager:

Using uv (Recommended)Using pip

uv add reflex-django

pip install reflex-django

---

Learning Path

We recommend exploring the documentation in this structured sequence to get a complete grasp of the integration:

1. Foundations

   • Introduction — Core concepts, philosophy, and comparison.
   • Installation — Dependencies, Django setup, and basic plugin configuration.
   • Configuration — Deep dive into the ReflexDjangoPlugin arguments and REFLEX_DJANGO_* settings.
   • Project Structure — Recommended folder layouts for monorepo development.

2. Core Architecture

   • Architecture Overview — Single-process dispatching, event bridges, and lifecycle hooks.
   • Routing & URL Dispatching — Managing paths across Reflex pages and Django prefixes.
   • API & HTTP Integration — Exposing Django REST Framework or standard Django views on /api.

3. State, Context & Auth

   • State Management — Synchronizing states between Python and the browser.
   • Django Context in Reflex — Running Django context processors per Socket.IO event.
   • Django Middleware in Reflex — How the Event Bridge brings request.user and session data to your event handlers.
   • Session Authentication — Full session authentication, permission decorators, and user sessions.
   • Internationalization (i18n) — Language negotiation, translated strings, RTL layouts, and the language switcher.

4. Database & CRUD Development

   • Database Integration — Migrations, asynchronous ORM calls, and model structures.
   • Model Serializers — Serializing complex Django models into JSON-safe Reflex variables.
   • CRUD Without Mixins — Step-by-step example of hand-rolled database actions.
   • ModelState vs ModelCRUDView — Choosing between high-level CRUD tools.
   • Reactive ModelState — Using ModelState for automatic form generation and live grids.
   • CRUD with Mixins & States — Customizing the ModelCRUDView workflow.
   • reflex-django Mixins — Standard mixin reference library.
   • Forms & Validation — Forms, error reporting, and UI resets.

5. Ops & Development

   • Command Line Interface — Leveraging the reflex django wrapper.
   • Testing Guide — Writing unit and integration tests.
   • Deployment Guide — Production configurations, static files, and environment requirements.
   • Best Practices — Guidelines for writing clean, performant, and secure apps.
   • FAQ — Answers to frequently asked questions.

---

Core Task Guide

Need to solve a specific problem? Check out these direct guides:

What do you want to do?	Recommended Guide
Configure Django settings and paths	Configuration Guide
Run Django database migrations	CLI Reference
Access Django sessions and request.user in event handlers	Session Authentication
Switch language, detect RTL, serve translated strings in Reflex	Internationalization (i18n)
Read raw query parameters (GET/POST) or cookies in state	Authentication — Accessing Request
Create a list, create, edit, or delete UI for a database model	Reactive ModelState or CRUD Without Mixins
Serialize database models into React-friendly dictionaries	Serializers Reference
Integrate DRF or standard Django HTTP views alongside the SPA	API & HTTP Integration
Deploy your unified app to a production server	Deployment Guide
Debug anonymous user sessions or authentication problems	FAQ

---

Maintainer Docs

To help maintain or contribute to the library:

• CHANGELOG.md — Full release history.
• RELEASING.md — Standard package publishing workflow.
• README.md — General package overview.

---

Navigation: Introduction →