Add ReactPy to a Django Project
Overview¶
If you want to add some interactivity to your existing Django project, you don't have to rewrite it in ReactPy. Use ReactPy-Django to add ReactPy to your existing stack, and render interactive components anywhere.
Note
These docs assumes you have already created a Django project, which involves creating and installing at least one Django app.
If do not have a Django project, check out this 9 minute YouTube tutorial created by IDG TECHtalk.
Step 1: Install from PyPI¶
Run the following command to install reactpy-django
in your Python environment.
pip install reactpy-django
Step 2: Configure settings.py
¶
Add "reactpy_django"
to INSTALLED_APPS
in your settings.py
file.
1 2 3 4 |
|
Enable ASGI and Django Channels (Required)
ReactPy-Django requires Django ASGI and Django Channels WebSockets.
If you have not enabled ASGI on your Django project yet, here is a summary of the django
and channels
installation docs:
- Install
channels[daphne]
-
Add
"daphne"
toINSTALLED_APPS
.INSTALLED_APPS = [ "daphne", ..., ]
-
Set your
ASGI_APPLICATION
variable.ASGI_APPLICATION = "example_project.asgi.application"
Configure ReactPy settings (Optional)
These are ReactPy-Django's default settings values. You can modify these values in your Django project's settings.py
to change the behavior of ReactPy.
Setting | Default Value | Example Value(s) | Description |
---|---|---|---|
REACTPY_CACHE | "default" | "my-reactpy-cache" | Cache used to store ReactPy web modules. ReactPy benefits from a fast, well indexed cache. We recommend installing redis or python-diskcache . |
REACTPY_DATABASE | "default" | "my-reactpy-database" | Database used to store ReactPy session data. ReactPy requires a multiprocessing-safe and thread-safe database. If configuring REACTPY_DATABASE , it is mandatory to enable our database router like such:DATABASE_ROUTERS = ["reactpy_django.database.Router", ...] |
REACTPY_SESSION_MAX_AGE | 259200 | 0 , 60 , 96000 | Maximum seconds to store ReactPy session data, such as args and kwargs passed into your component template tag. Use 0 to not store any session data. |
REACTPY_URL_PREFIX | "reactpy/" | "rp/" , "render/reactpy/" | The prefix to be used for all ReactPy WebSocket and HTTP URLs. |
REACTPY_DEFAULT_QUERY_POSTPROCESSOR | "reactpy_django.utils.django_query_postprocessor" | None , "example_project.my_query_postprocessor" | Dotted path to the default reactpy_django.hooks.use_query postprocessor function. Postprocessor functions can be async or sync, and the parameters must contain the arg data . Set REACTPY_DEFAULT_QUERY_POSTPROCESSOR to None to globally disable the default postprocessor. |
REACTPY_AUTH_BACKEND | "django.contrib.auth.backends.ModelBackend" | "example_project.auth.MyModelBackend" | Dotted path to the Django authentication backend to use for ReactPy components. This is only needed if: 1. You are using AuthMiddlewareStack and...2. You are using Django's AUTHENTICATION_BACKENDS setting and...3. Your Django user model does not define a backend attribute. |
REACTPY_BACKHAUL_THREAD | False | True | Whether to render ReactPy components in a dedicated thread. This allows the web server to process traffic during ReactPy rendering. Vastly improves throughput with web servers such as hypercorn and uvicorn . |
REACTPY_DEFAULT_HOSTS | None | ["localhost:8000", "localhost:8001", "localhost:8002/subdir" ] | The default host(s) that can render your ReactPy components. ReactPy will use these hosts in a round-robin fashion, allowing for easy distributed computing. You can use the host argument in your template tag as a manual override. |
REACTPY_RECONNECT_INTERVAL | 750 | 100 , 2500 , 6000 | Milliseconds between client reconnection attempts. This value will gradually increase if REACTPY_RECONNECT_BACKOFF_MULTIPLIER is greater than 1 . |
REACTPY_RECONNECT_MAX_INTERVAL | 60000 | 10000 , 25000 , 900000 | Maximum milliseconds between client reconnection attempts. This allows setting an upper bound on how high REACTPY_RECONNECT_BACKOFF_MULTIPLIER can increase the time between reconnection attempts. |
REACTPY_RECONNECT_MAX_RETRIES | 150 | 0 , 5 , 300 | Maximum number of reconnection attempts before the client gives up. |
REACTPY_RECONNECT_BACKOFF_MULTIPLIER | 1.25 | 1 , 1.5 , 3 | Multiplier for the time between client reconnection attempts. On each reconnection attempt, the REACTPY_RECONNECT_INTERVAL will be multiplied by this to increase the time between attempts. You can keep time between each reconnection the same by setting this to 1 . |
Step 3: Configure urls.py
¶
Add ReactPy HTTP paths to your urlpatterns
in your urls.py
file.
1 2 3 4 5 6 |
|
Step 4: Configure asgi.py
¶
Register ReactPy's WebSocket using REACTPY_WEBSOCKET_ROUTE
in your asgi.py
file.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
|
Add AuthMiddlewareStack
and SessionMiddlewareStack
(Optional)
There are many situations where you need to access the Django User
or Session
objects within ReactPy components. For example, if you want to:
- Access the
User
that is currently logged in - Login or logout the current
User
- Access Django's
Session
object
In these situations will need to ensure you are using AuthMiddlewareStack
and/or SessionMiddlewareStack
.
from channels.auth import AuthMiddlewareStack # noqa: E402
from channels.sessions import SessionMiddlewareStack # noqa: E402
application = ProtocolTypeRouter(
{
"http": django_asgi_app,
"websocket": SessionMiddlewareStack(
AuthMiddlewareStack(
URLRouter(
[REACTPY_WEBSOCKET_ROUTE],
)
)
),
}
)
Where is my asgi.py
?
If you do not have an asgi.py
, follow the channels
installation guide.
Step 5: Run database migrations¶
Run Django's migrate
command to initialize ReactPy-Django's database table.
python manage.py migrate
Step 6: Check your configuration¶
Run Django's check
command to verify if ReactPy was set up correctly.
python manage.py check
Step 7: Create your first component¶
The next step will show you how to create your first ReactPy component.
Prefer a quick summary? Read the At a Glance section below.
At a Glance: Your First Component
my_app/components.py
You will need a file to define your ReactPy components. We recommend creating a components.py
file within your chosen Django app to start out. Within this file, we will create a simple hello_world
component.
1 2 3 4 5 |
|
my_app/templates/my-template.html
In your Django app's HTML template, you can now embed your ReactPy component using the component
template tag. Within this tag, you will need to type in the dotted path to the component.
Additionally, you can pass in args
and kwargs
into your component function. After reading the code below, pay attention to how the function definition for hello_world
(from the previous example) accepts a recipient
argument.
1 2 3 4 5 6 7 |
|