djust 1.3.1

Reactive server-side rendering for Django, powered by Rust

djust brings Phoenix LiveView-style reactive views to Django. You write server-side Python; the browser updates itself over a WebSocket. There is no JavaScript to write, no bundler, and no build step in your project.

djust.org · Documentation · Quick Start · Examples

from djust import LiveView, event_handler

class CounterView(LiveView):
    template = """
    <div dj-root>
        <h1>Count: {{ count }}</h1>
        <button dj-click="increment">+</button>
        <button dj-click="decrement">-</button>
    </div>
    """

    def mount(self, request, **kwargs):
        self.count = 0

    @event_handler
    def increment(self):
        self.count += 1  # the page updates; no JavaScript

    @event_handler
    def decrement(self):
        self.count -= 1

Why djust

• One codebase. Views, state and event handlers are Python. No API layer, no frontend build.
• Small wire traffic. A Rust virtual DOM diffs each render and sends only the changed patches.
• Fast templates. A Rust template engine renders Django templates 7–11x faster on variable- and filter-heavy pages (Performance).
• Tiny client. ~80 KB gzipped runtime, injected automatically. Nothing to bundle.
• Django all the way down. Your templates, forms, auth, permissions and ORM work as they are, with CSRF, escaping and per-view authorization built in.
• Resilient transport. WebSocket with automatic reconnection and an HTTP fallback.

Getting started

The fastest start is the scaffold, which configures everything below:

pip install djust
djust new myproject

To add djust to an existing project instead:

1. Settings. Add the apps and a channel layer to settings.py:

INSTALLED_APPS = [
    # ... your existing apps ...
    "channels",
    "djust",
]

ASGI_APPLICATION = "myproject.asgi.application"

CHANNEL_LAYERS = {"default": {"BACKEND": "channels.layers.InMemoryChannelLayer"}}

2. asgi.py. Route WebSockets to djust:

import os
from django.core.asgi import get_asgi_application

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
django_asgi_app = get_asgi_application()  # sets Django up before the imports below

from django.contrib.staticfiles.handlers import ASGIStaticFilesHandler
from django.urls import path
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.auth import AuthMiddlewareStack
from djust.websocket import LiveViewConsumer

application = ProtocolTypeRouter({
    # ASGIStaticFilesHandler serves /static/ (djust's client.js included)
    # under uvicorn or daphne in development, as runserver would.
    "http": ASGIStaticFilesHandler(django_asgi_app),
    "websocket": AuthMiddlewareStack(
        URLRouter([path("ws/live/", LiveViewConsumer.as_asgi())])
    ),
})

3. A view, a URL and a template.

# myapp/views.py
from djust import LiveView, event_handler

class CounterView(LiveView):
    template_name = "counter.html"

    def mount(self, request, **kwargs):
        self.count = 0

    @event_handler
    def increment(self):
        self.count += 1

# myproject/urls.py
from django.urls import path
from myapp.views import CounterView

urlpatterns = [path("counter/", CounterView.as_view(), name="counter")]

<!-- myapp/templates/counter.html -->
{% load live_tags %}
<!DOCTYPE html>
<html>
<head>
    <title>Counter</title>
    {% djust_client_config %}
</head>
<body>
    <div dj-root>
        <h1>Count: {{ count }}</h1>
        <button dj-click="increment">+</button>
    </div>
</body>
</html>

4. Run it with uvicorn myproject.asgi:application and open /counter/. In DEBUG, djust hot-reloads views without restarting or losing state, so you don't need --reload.

How reactivity works

On each event djust re-renders the view on the server, diffs the result against the previous render in Rust, and sends only the patches.

{% for item in items %}
<div dj-key="{{ item.id }}">{{ item.name }}</div>
{% endfor %}

Without a key, lists are diffed by position: still correct, with more DOM changes on reorders. Conditional attributes such as class="btn {% if active %}active{% endif %}" are handled correctly too, with or without {% else %}. See the VDOM architecture guide and the template cheat sheet.

Rust templates for any Django view

You don't need LiveView to use the Rust engine. Point a TEMPLATES entry at the backend, and your existing TemplateViews, render() calls and {% include %}s render through Rust, with no WebSocket and no client runtime:

TEMPLATES = [
    {
        "BACKEND": "djust.template.backend.DjustTemplateBackend",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {"context_processors": [...]},
    },
    {
        # admin and contrib templates still need Django's own backend
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [],
        "APP_DIRS": True,
        "OPTIONS": {"context_processors": [...]},
    },
]

• 98.57% of Django's own template_tests suite passes unmodified against this backend (1032 of the 1,047 cells that reach an engine at all; measured by scripts/run-django-template-suite.py against the Django tag matching the installed version — see docs/TEMPLATE_BACKEND.md for the full breakdown and what the remaining cells are).
• Rendering is 7–11x faster on variable- and filter-heavy templates; static markup is not faster, because there is nothing to accelerate.

djust new configures this backend for you.

Performance

Full render, same template on both engines, parsed once on each side. benchmarks/benchmark.py on an Apple silicon laptop, Django 5.2.16, Python 3.12, DEBUG=False, release build:

The speedup grows with variable and filter density. The table leaves out the bigger win on updates, where djust sends a diff and plain Django re-sends the whole page. Reproduce it with make build && python benchmarks/benchmark.py. The script refuses a debug build, which is roughly 7.6x slower.

Learn more

Everything else is at docs.djust.org. Working examples live in examples/demo_project.

Architecture

Browser        client runtime (~80 KB gz) ── events up, patches down
   ↕ WebSocket (or HTTP fallback)
Django         LiveView classes, event handlers, state (Python, Channels)
   ↕ PyO3
Rust core      template engine · VDOM diff · HTML parser · MessagePack

Development

Building from source needs Rust 1.70+ and uv:

git clone https://github.com/djust-org/djust.git
cd djust
make install   # dependencies via uv, then a release build of the Rust core
make test      # Python + Rust + JavaScript
make help      # everything else

See CONTRIBUTING.md and the testing guide.

Security

CSRF protection, automatic escaping in the Rust engine, WebSocket origin validation and session auth, rate limiting, and view- and handler-level permissions are built in; manage.py djust_audit reports your views' auth posture. Report vulnerabilities to security@djust.org (see SECURITY.md).

Community

• djust.org · Documentation · Issues · support@djust.org
• Discord · YouTube: short explainers and real runs
• Sponsor on GitHub, or star the repo to help others find it.

MIT licensed (LICENSE). Inspired by Phoenix LiveView; built with PyO3 and html5ever.