Home Features Docs Blog Security Examples Quick Start
Get Started GitHub

Core Concepts

Understanding the fundamental concepts behind djust's reactive server-side rendering.

Architecture

djust connects browser interactions to server-side state through WebSocket or HTTP. The client (Browser (Client)) contains DOM (HTML) and djust.js (~5KB), communicating via WebSocket/HTTP with the server (Server (Django)).

LiveView

A LiveView is a Django view that maintains state between requests and updates the UI reactively. Unlike traditional request-response views, LiveViews stay connected and can push updates to the client in real-time.

Lifecycle Methods

Method When Called Purpose
mount(request, **kwargs) Initial page load Initialize state
render() After any state change Return HTML (auto-called)
handle_params(params) URL params change React to URL changes
terminate() Session ends Cleanup resources

Example LiveView

views.py 
 1fromdjustimport LiveView, event
 2
 3classCounterView(LiveView):
 4    template_name = 'counter.html'
 5
 6    defmount(self, request, **kwargs):
 7"""Called when the view first loads."""
 8        self.count = 0
 9
10    @event
11    defincrement(self):
12"""Event handler for increment button."""
13        self.count += 1
14
15    @event
16    defdecrement(self):
17"""Event handler for decrement button."""
18        self.count -= 1

Example Template

templates/counter.html 
1<div dj-liveview>
2    <h1>Count: {{ count }}</h1>
3
4    <button dj-click="decrement">-</button>
5    <button dj-click="increment">+</button>
6</div>

Events

Events connect user interactions to server-side handlers. Use dj-* attributes in your templates to bind events.

Event Bindings

Attribute Description Example
dj-click Handle click events
dj-input Handle input on every keystroke
dj-change Handle input on blur (leaving field)
dj-submit Handle form submission
...
dj-keydown Handle keyboard events

Key Concepts

  • Server-Side State - All state lives on the server. No client-side state management needed.
  • Reactive Updates - When state changes, only the changed parts of the DOM are updated.
  • VDOM Diffing - Rust-powered virtual DOM calculates minimal patches for efficient updates.
  • Event Handlers - Any method can handle events. Use @event decorator for explicit marking.

VDOM Architecture

djust uses a Rust-powered Virtual DOM for efficient updates. Instead of re-sending the entire page, only the differences (patches) are sent. 

1. Server renders HTML template
2. Rust parses HTML into VDOM tree
3. Client receives initial HTML
4. On state change:
   a. Server re-renders template
   b. Rust diffs old vs new VDOM
   c. Only differences sent to client
   d. Client patches DOM surgically

Performance Benefit

Approach Update 1 item in 1000-item list
Full re-render Send ~50KB, replace entire DOM
djust VDOM Send ~100 bytes, patch 1 element

Next Steps