Quick Start Guide

Build your first real-time Django app with djust in 5 minutes. No JavaScript required.

Prerequisites

Python 3.9+

Check: python --version

Django 4.2+

Or we'll install it for you

Rust 1.70+

For building the VDOM engine

Basic Django knowledge

Views, templates, URLs

Install djust

Install djust via pip. This will also install Django and other dependencies.

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install djust
pip install djust

Create a Django Project

Create a new Django project or use an existing one.

# Create new Django project
django-admin startproject myproject
cd myproject

# Create an app
python manage.py startapp counter

Configure Django Settings

Add djust and Channels to your INSTALLED_APPS in settings.py

# myproject/settings.py

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',

    'channels',  # Required for WebSocket
    'djust',     # djust framework
    'counter',   # Your app
]

# Configure ASGI
ASGI_APPLICATION = 'myproject.asgi.application'

Setup ASGI Routing

Configure WebSocket routing in asgi.py

# myproject/asgi.py

import os
from django.core.asgi import get_asgi_application
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.auth import AuthMiddlewareStack
from django.urls import path
from djust.websocket import LiveViewConsumer

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')

application = ProtocolTypeRouter({
    "http": get_asgi_application(),
    "websocket": AuthMiddlewareStack(
        URLRouter([
            path('ws/live/', LiveViewConsumer.as_asgi()),
        ])
    ),
})

Create Your First LiveView

Create a simple counter with real-time updates in counter/views.py

# counter/views.py

from djust import LiveView

class CounterView(LiveView):
    template_name = 'counter/counter.html'

    def mount(self, request):
        """Called when the view is first loaded"""
        self.count = 0

    def increment(self):
        """Event handler - called when user clicks increment"""
        self.count += 1

    def decrement(self):
        """Event handler - called when user clicks decrement"""
        self.count -= 1

    def reset(self):
        """Event handler - called when user clicks reset"""
        self.count = 0

    def get_context_data(self, **kwargs):
        """Return context for template rendering"""
        return {'count': self.count}

Create the Template

Create counter/templates/counter/counter.html

<!-- counter/templates/counter/counter.html -->
<!DOCTYPE html>
<html>
<head>
    <title>Counter Example</title>
    {% load static %}
    <script src="{% static 'djust/client.js' %}"></script>
</head>
<body>
    <div style="text-align: center; padding: 2rem;">
        <h1>Counter Example</h1>

        <div style="font-size: 4rem; margin: 2rem 0;">
            {{ count }}
        </div>

        <div>
            <button @click="decrement">-</button>
            <button @click="reset">Reset</button>
            <button @click="increment">+</button>
        </div>
    </div>
</body>
</html>

Note: The @click attribute binds click events to your Python methods. No JavaScript needed!

Configure URLs

Add the URL pattern to myproject/urls.py

# myproject/urls.py

from django.contrib import admin
from django.urls import path
from counter.views import CounterView

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', CounterView.as_view(), name='counter'),
]

Run the Development Server

Start the server and see your counter in action!

python manage.py runserver

Success!

Open http://localhost:8000 in your browser. Click the buttons and watch the counter update in real-time!

How It Works

Initial Load

When you visit the page, Django renders the template with count = 0 and sends full HTML to the browser.

WebSocket Connection

The djust client JavaScript establishes a WebSocket connection to the server, creating a live session.

User Clicks Button

When you click "increment", the client sends an event to the server: {"event": "increment"}

Server Updates State

The server calls self.increment(), updating self.count = 1

VDOM Diff (Rust)

djust's Rust engine re-renders the template and compares it to the previous version, generating minimal patches in <100μs.

Client Updates DOM

The client receives patches like [{path: [2,0], text: "1"}] and updates only the counter number. No full page reload!

Next Steps

Explore Examples

See more complex examples like forms, todo lists, and data tables.

Read the Docs

Deep dive into components, forms, state management, and more.

Join Discord

Get help, share your projects, and connect with the community.

Star on GitHub

Check out the source code, report issues, and contribute.

Need Help?

Stuck on something? Check out the full documentation or ask the community for help.

Full Documentation Ask on Discord