Configuration reference

Every key of djust's LiveView configuration, with its default, generated from the framework's defaults and the comments written beside them.

Set keys in the LIVEVIEW_CONFIG dict in your Django settings; anything you leave out keeps its default. A key placed in DJUST_CONFIG instead is also honoured, but LIVEVIEW_CONFIG wins when both set it.

# settings.py
LIVEVIEW_CONFIG = {
    "serialization_max_depth": 4,
    "rate_limit": {"rate": 200, "burst": 40},
}

Per-view settings are class attributes instead: see Class attributes.

46 keys.

rate_limit

Type: dict

Rate limiting for WebSocket events (token bucket).

max_message_size

Type: int · Default: 65536

Maximum incoming WebSocket message size in bytes (0 = no limit). 64KB.

event_security

Type: str · Default: 'strict'

Event security mode: "open", "warn", or "strict". "open" - no decorator check (legacy behavior). "warn" - allow unmarked methods but log deprecation warning. "strict" - only @event_handler decorated methods.

use_websocket

Type: bool · Default: True

LiveView transport mode. Set to False to use HTTP polling instead of WebSocket.

websocket_compression

Type: bool · Default: True

WebSocket per-message compression advisory flag (v0.6.0). permessage-deflate negotiation actually happens in the ASGI. server — Uvicorn/Daphne both support it by default. This flag. is the declarative "we want compression" signal that. djust_audit / debug-panel introspection surface, and that. application code can branch on (e.g. to skip a manual. JSON.stringify optimization that only helps without the. wire-level compress). Costs ~64 KB of zlib context per open. connection — disable on extreme-connection-density. deployments (100k+/worker). Override via. settings.DJUST_WS_COMPRESSION. Also settable as the Django setting DJUST_WS_COMPRESSION.

debug_vdom

Type: bool · Default: False

Debug settings. Enable detailed VDOM patching debug logs.

debug_components

Type: bool · Default: False

Deprecated, never read (#2984; djust.C018; removed in 1.3).

Defined but not read by djust 1.2.2; setting it has no effect. Deprecated: djust.C018 warns when it is set, and djust 1.3 removes it.

debug_panel_max_history

Type: int · Default: 50

Maximum number of events/patches to keep in debug panel history.

debug_auto_open_on_error

Type: bool · Default: False

Auto-open debug panel on first error/warning (DEBUG mode only).

Read only by the debug panel, from window.LIVEVIEW_CONFIG in the browser; djust does not copy this setting there, so it takes effect only if your page defines that object itself.

hook_namespacing

Type: str · Default: 'lax'

Colocated JS hook namespacing (Phoenix 1.1 parity). "lax" - bare hook name, no prefix (default, compat). "strict" - prefix with <view-module>.<view-qualname> so two views. can both define Chart without colliding. Per-tag opt-out: {% colocated_hook "X" global %} always emits bare name. This is also readable from settings.DJUST_CONFIG["hook_namespacing"]. via the template tag (kept here for discoverability / system-check tooling).

auto_navigate

Type: bool · Default: True

Automatic SPA navigation (#1734, ADR-021). When True, {% djust_client_config %} emits a <meta name="djust-auto-navigate">. flag (and auto-emits the route map, #1733) and the client installs ONE. delegated click listener that SPA-navigates plain <a href> links whose. path resolves in the (auth-filtered, #1758) route map — Turbo-Drive-. style, no djust attributes needed. Default ON as of v1.1 (ADR-021 Stage 3): native dj-navigate is djust's. canonical SPA-navigation model, so it is the zero-config default. It. degrades gracefully — links whose path does NOT resolve in the route. map (external, non-LiveView, etc.) full-reload exactly as before, and. the opt-out matrix still applies (modifier/middle-click, target/. download, hash-only, data-no-navigate). Opt OUT with. LIVEVIEW_CONFIG["auto_navigate"] = False (e.g. apps that wire their. own external TurboNav). On 1.0.x this defaulted OFF (opt-in).

reauth_on_event

Type: bool · Default: False

Re-check auth on every WS event (#1777, threat model T3, defense-in-depth). Auth normally runs only at mount; with this OFF (default) an. authenticated user who logs out / loses a permission mid-session keeps. dispatching events on the open socket until they reconnect (the. connect-time scope user is cached). When True, handle_event re-resolves. the user from the session (channels.auth.get_user) and re-runs the. view's login_required/permission_required check, closing 4403 on. failure. Default OFF: it costs one session read per event — opt in for. high-security apps that want mid-session deauth enforced on the live path.

hot_reload

Type: bool · Default: True

Hot Reload (Development). Enable hot reload in development (requires DEBUG=True).

hot_reload_watch_dirs

Type: NoneType · Default: None

Directories to watch (None = auto-detect BASE_DIR).

hot_reload_exclude_dirs

Type: NoneType · Default: None

Directories to exclude (None = use defaults).

hot_reload_auto_enable

Type: bool · Default: True

Auto-call enable_hot_reload() from DjustConfig.ready() in DEBUG. Set to False if you orchestrate the file watcher externally (e.g. watchfiles wrapping uvicorn) and want full manual control.

update_check

Type: bool · Default: True

Once-a-day notice of newer releases / security advisories on the. dev server and in manage.py check. Cached, silent on failure, never runs with DEBUG=False. See docs/website/guides/update-check.md.

hvr_enabled

Type: bool · Default: True

Hot View Replacement (v0.6.1) — state-preserving Python code. reload in dev. Gated on DEBUG=True AND hot_reload=True.

time_travel_enabled

Type: bool · Default: False

Time-travel debugging (v0.6.1) — dev-only. Master switch for. the global default (views still opt in via. LiveView.time_travel_enabled = True). time_travel_max_events. caps per-view ring buffer size (memory-bound).

time_travel_max_events

Type: int · Default: 100

bug_capture_default_scrub

Type: list · Default: []

Bug-capture (B7 iter B, #1562) — default scrub field names applied. by the debug panel's "Share" button before it calls. encode_view_state(). Empty by default (no default scrub); set. e.g. LIVEVIEW_CONFIG['bug_capture_default_scrub'] = ["password"]. to redact known-sensitive top-level state keys on every share. without requiring a per-call scrub_fields(...) argument. Only. consulted by the WS "Share" button path. (LiveViewConsumer.handle_bug_capture_share) — the programmatic. encode_view_state() API always requires an explicit scrub. argument from the caller.

jit_serialization

Type: bool · Default: True

JIT Serialization (Phase 5). False skips JIT auto-serialization (#2984).

jit_debug

Type: bool · Default: False

Debug logging for JIT serialization.

jit_cache_backend

Type: str · Default: 'filesystem'

Deprecated, never read (#2984; djust.C018 warns when set, removed in 1.3):

Defined but not read by djust 1.2.2; setting it has no effect. Deprecated: djust.C018 warns when it is set, and djust 1.3 removes it.

jit_cache_dir

Type: str · Default: '__pycache__/djust_serializers'

Defined but not read by djust 1.2.2; setting it has no effect. Deprecated: djust.C018 warns when it is set, and djust 1.3 removes it.

jit_redis_url

Type: str · Default: 'redis://localhost:6379/0'

Defined but not read by djust 1.2.2; setting it has no effect. Deprecated: djust.C018 warns when it is set, and djust 1.3 removes it.

serialization_max_depth

Type: int · Default: 3

Max depth for nested model serialization (e.g., lease.tenant.user = 3 levels).

strict_serialization

Type: bool · Default: False

Serialization behavior (issue #292). When False (default): non-serializable values are converted via str() fallback with a warning log. When True: non-serializable values raise TypeError with actionable error message. Always emits warning logs before fallback, even in non-strict mode. Raise TypeError for non-serializable values instead of str() fallback.

loop_render_cache_enabled

Type: bool · Default: True

Per-item loop render cache (#1967/#1969/#1970). When True, the Rust. renderer caches each loop item's rendered fragment (and parsed VNode. subtree) by a content hash and reuses them across render_with_diff(). calls, turning a pure reorder of a large keyed list from O(n). re-renders into O(changed). Default ON since #2062 (graduated after. soaking flag-OFF from v1.1.0rc5, with byte-identity ON==OFF proven. across the template matrix and the #2067 cross-loop keyspace fix. landed first). Set False to opt OUT (kill-switch). Only applies to. position-INDEPENDENT loop bodies that read nothing but the loop. variable; bodies using {% if %}/{% cycle %}/nested loops/forloop or. outer-context reads are auto-excluded (correct by construction).

virtual_keyed_ops

Type: bool · Default: True

[dj-virtual] keyed splice ops in the VDOM differ (ADR-026, #2017. items 2-4). A windowed list holds off-window rows DETACHED, so the. index-addressed ops the differ normally emits are meaningless for it: index 7 means "the 8th item" to the differ and "the 8th VISIBLE item". to the DOM. These ops address items by KEY instead, so an insert in. the middle, a removal, or an update to an off-window row all land. correctly instead of at the tail. Wired to the process-global Rust switch once at startup by. DjustConfig.ready() — it is not per-view state. ADR-026 iteration 3: default ON since 1.1.0. Gated on real browser evidence (ROADMAP), and the A/B that finally. produced it needed BOTH #2185 and #2194 fixed first — until then the. list was intermittently never initialised, so the control arm was as. broken as the test arm and no comparison meant anything. Measured on. a healthy, initialised [dj-virtual] list, same start state, flag the. only variable: OFF ON. insert at position 5 pool index 60 (tail) pool index 5. remove at 3 size unchanged, k3 kept k3 gone, no dupes. reverse not reordered exact reversal. edit a scrolled row correct correct. So OFF is broken for every mid-list structural mutation on a windowed. list, and ON fixes all three without regressing the one case OFF got. right. 0 console errors, no VirtualInsert/Move/Remove warnings. Scope: the ops are emitted ONLY for a container carrying dj-virtual. (emits_virtual_ops in crates/djust_vdom/src/diff.rs), so a project. that does not use dj-virtual sees no wire change at all. Version skew: a cached PRE-1.1.0 client bundle talking to a 1.1.0+. server receives Virtual* ops its applier does not know. That degrades. to the existing patch-failure path — the client requests recovery HTML. and morphs — rather than breaking. Set this to False to opt out.

django_value_repr

Type: bool · Default: True

Django-parity value rendering (#2203). When True (default), a value. interpolated with {{ }} renders as Python's str() does — which is. what Django does: {{ flag }} -> True (was: true). {{ none }} -> None (was: empty; an ABSENT variable still. renders empty, as Django's. string_if_invalid does). {{ 1.0 }} -> 1.0 (was: 1). {{ [1, 2] }} -> [1, 2] (was: the placeholder [List]). {{ {'a':1} }}-> {'a': 1} (was: the placeholder [Object]). {{ (1, 2) }} -> (1, 2) (was: [List]). This is not only cosmetic: Display is the lookup key for. {% if x in some_dict %}, so {% if True in d %} used to MISS where. Django hits. Set to False if a template interpolates a bool directly into a script. block — var f = {{ flag }}; renders valid JS today and becomes a. ReferenceError under Django semantics. Django has the same hazard; its. answers are |yesno:"true,false" and {{ data|json_script:"id" }}, and those work here too.

template_auto_call

Type: bool · Default: True

Django-parity template auto-call (ADR-024). When True (default), the Rust engine's sidecar getattr walk invokes callables exactly. like Django's Variable._resolve_lookup ({{ user.get_full_name }}, {{ workspace.memberships.count }}), honoring. do_not_call_in_templates and refusing alters_data. False restores. the pre-ADR plain-getattr behavior — a kill-switch only, not a. feature toggle (candidate for removal at 2.0).

sensitive_field_types

Type: list · Default: []

#1987: TYPE-based serialization floor (defense-in-depth over the. name/method floor). A list of Django field CLASS names (matched. anywhere in a field's MRO) to always exclude from client-bound. serialization — e.g. ["BinaryField", "MyEncryptedField"]. BinaryField. and best-effort encrypted-field types are excluded unconditionally; this adds project-specific types. FileField/ImageField are never. excluded (they serialize a URL).

css_framework

Type: str · Default: 'bootstrap5'

CSS Framework. Options: 'bootstrap4', 'bootstrap5', 'tailwind', None.

bootstrap4

Type: dict

Bootstrap 4 classes (NYC Core Framework, gov sites, legacy projects).

bootstrap5

Type: dict

Bootstrap 5 classes.

tailwind

Type: dict

Tailwind CSS classes.

plain

Type: dict

Plain HTML (no framework).

render_labels

Type: bool · Default: True

Field rendering options.

render_help_text

Type: bool · Default: True

render_errors

Type: bool · Default: True

auto_validate_on_change

Type: bool · Default: True

component_wrapper_class

Type: str · Default: ''

Component defaults. Deprecated, never read (#2984; djust.C018 warns. when set; removed in 1.3):

Defined but not read by djust 1.2.2; setting it has no effect. Deprecated: djust.C018 warns when it is set, and djust 1.3 removes it.

component_loading_class

Type: str · Default: 'loading'

Defined but not read by djust 1.2.2; setting it has no effect. Deprecated: djust.C018 warns when it is set, and djust 1.3 removes it.

service_worker

Type: dict

Service worker (v0.5.0 P3) — opt-in instant shell + reconnection bridge. These values are informational for tooling / system checks; the. actual runtime knobs live in the client-side registration call. (djust.registerServiceWorker({...})) and in the SW itself.

loading_grouping_classes

Type: list · Default: ['d-flex', 'btn-group', 'input-group', 'form-group', 'btn-toolbar']

@loading attribute configuration (Phase 5). Bootstrap flex container. Bootstrap button group. Bootstrap input group. Bootstrap form group. Bootstrap button toolbar.