Documentation

HyperDjango Documentation

Start here for the core ideas, the Django-first mental model, and how the docs are organized.

Start with Getting Started, then move through routing, rendering, and the reference pages once the core concepts are clear.

HyperDjango gives Django a server-first workflow with file routing, colocated assets, and hypermedia actions.

Use it when you want interactive UX without splitting your app into separate backend API and SPA frontend codebases.

Current Release: 0.40.1

HyperDjango 0.40.1 makes the standalone Request Inspector quieter and more focused:

  • keep the inspector hidden until the DOM, stylesheet, and initial trace state are ready
  • set HYPER_DEBUG_TOOLBAR_CONFIG["RECORD_PAGE_REQUESTS"] = False to retain only Hyper action requests while keeping the launcher available on HTML pages
  • exclude Django Debug Toolbar's internal polling endpoints from HyperDjango capture even when DJDT is mounted under a custom path
  • restore a previously open inspector immediately on refresh without replaying the drawer animation

See the Request Inspector guide for configuration and behavior. The 0.39 command-to-query handoff remains documented under action.switch_to(...).

Existing projects should also review the 0.38.0 project upgrade notes, especially the Vite 8 and Node.js requirements. The production checklist covers the final validation steps.

Core Ideas

  • file-based routing for Django pages
  • automatic asset loading for pages, layouts, and template packages
  • hypermedia actions that return HTML, events, redirects, history updates, and small client patches

Relationship to Alpine

HyperDjango works without Alpine, but Alpine is the client-side library it integrates with most closely.

  • HyperDjango core: works with plain JavaScript through hyper.js
  • Alpine integration: recommended layer for $action(...) and signal patching

Documentation Map

The docs are split by concept ownership:

  • start with getting a page working
  • then learn routing, rendering, layouts, and actions
  • then learn client-side invocation and declarative HTML APIs
  • use the reference section for exact runtime details
Guides

Getting Started

Install HyperDjango, wire Django settings, mount routes, and build the first page and action.

Routing

Learn file-based routing, nested pages, dynamic params, typed params, regex routes, and reverse names.

Pages and Rendering

Understand HyperView, plain Django View, render helpers, template packages, and standalone template rendering.

Layouts

Use reusable layout packages in hyper/layouts to share templates, assets, and server behavior.

Base Template

Understand the shipped hyperdjango/base.html template, what it includes by default, and how to replace it safely.

Actions

Write HyperDjango actions, return typed response items, and understand immediate versus streaming responses.

History

Update browser history from actions and restore full or partial pages safely during back and forward navigation.

Client-Side Actions

Invoke actions from Alpine or plain JavaScript and understand sync, key, upload progress, and runtime events.

Declarative HTML APIs

Use hyper-form-disable, hyper-loading, and hyper-view-transition-name when declarative HTML is clearer than inline JavaScript.

Alpine Integration

Learn how HyperDjango integrates with Alpine through $action, local signal patches, and the global $store.hyper bridge.

Assets and Vite

Understand automatic entry discovery, Vite development and production asset loading, and template asset tags.

Request Inspector

Enable and use HyperDjango's standalone request inspector for routes, actions, output, SSE streams, timings, SQL, and browser outcomes.

Django Debug Toolbar

Add HyperDjango diagnostics as an optional custom panel inside Django Debug Toolbar.

Troubleshooting

Debug common issues such as missing targets, CSRF failures, route conflicts, and view transition expectations.

Production Checklist

Validate production settings, caching, static assets, and request behavior before shipping HyperDjango pages.

FAQ

Quick answers for View vs HyperView, layout choices, render helpers, Alpine, and action return patterns.
Reference

Overview

Start here for the API-style reference pages.

Django Integration

Exact reference for include_routes and Django URL wiring.

Settings

Exact reference for frontend, Vite, development-server, and request-inspector settings.

Pages and Rendering

Method signatures and return details for HyperView, HyperPageTemplate, and rendering shortcuts.

Actions

Detailed arguments and supported return shapes for action items and action methods.

Asset Resolver

Reference for resolving page, layout, template, development-server, and production-manifest assets.

Client Runtime

Detailed reference for $action, window.action, runtime outcomes, and browser events.

Exceptions

Reference for HyperDjango exception types and the runtime conditions that raise them.

HTML APIs

Reference for hyper-form-disable, hyper-view-transition-name, and loading-related attributes.

SSE Payloads

Wire-format reference for streamed action events, event IDs, retries, and resume behavior.

Template Tags

Reference for hyper_preloads, hyper_stylesheets, hyper_head_scripts, hyper_body_scripts, and hyper_custom_entry.

Commands

Reference for hyper_runserver, hyper_scaffold, and hyper_routes.
Examples

Examples Overview

Find practical recipes and the complete runnable example application.

Cookbook

Copy practical patterns for signals, partial swaps, streaming, navigation, uploads, and reusable UI flows.

Example App

Run the bundled project and explore its routes, actions, layouts, dynamic segments, and browser tests.