Skip to content

Install ReactPy-Django

Overview

ReactPy-Django can be used to add used to add ReactPy support to an existing Django project. Minimal configuration is required to get started.

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

pip install reactpy-django

Step 2: Configure settings.py

In your settings you will need to add reactpy_django to INSTALLED_APPS.

1
2
3
4
INSTALLED_APPS = [
    ...,
    "reactpy_django",
]
Enable Django Channels ASGI (Required)

ReactPy-Django requires ASGI Websockets from Django Channels.

If you have not enabled ASGI on your Django project yet, you will need to

  1. Install channels[daphne]
  2. Add daphne to INSTALLED_APPS
  3. Set your ASGI_APPLICATION variable.
1
2
3
4
5
INSTALLED_APPS = [
    "daphne",
    ...,
]
ASGI_APPLICATION = "example_project.asgi.application"

Consider reading the Django Channels Docs for more info.

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 use 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" "example_project.my_query_postprocessor" Dotted path to the default reactpy_django.hooks.use_query postprocessor function.
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 webserver to process web traffic while 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.

1
2
3
4
5
6
from django.urls import include, path

urlpatterns = [
    ...,
    path("reactpy/", include("reactpy_django.http.urls")),
]

Step 4: Configure asgi.py

Register ReactPy's Websocket using REACTPY_WEBSOCKET_ROUTE.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import os

from django.core.asgi import get_asgi_application

# Ensure DJANGO_SETTINGS_MODULE is set properly based on your project name!
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "example_project.settings")

# Fetch ASGI application before importing dependencies that require ORM models.
django_asgi_app = get_asgi_application()


from channels.routing import ProtocolTypeRouter, URLRouter  # noqa: E402
from reactpy_django import REACTPY_WEBSOCKET_ROUTE  # noqa: E402

application = ProtocolTypeRouter(
    {
        "http": django_asgi_app,
        "websocket": URLRouter([REACTPY_WEBSOCKET_ROUTE]),
    }
)
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:

  1. Access the User that is currently logged in
  2. Login or logout the current User
  3. 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 database migrations 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 following steps will show you how to create your first ReactPy component.

Prefer a quick summary? Read the At a Glance section below.

At a Glance

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
from reactpy import component, html

@component
def hello_world(recipient: str):
    return html.h1(f"Hello {recipient}!")

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
{% load reactpy %}
<!DOCTYPE html>
<html>
  <body>
    {% component "example_project.my_app.components.hello_world" recipient="World" %}
  </body>
</html>
Last update: August 26, 2023
Authors: Mark Bakhit