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.
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
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.
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.
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.
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.
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.
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.
Overview
Start here for the API-style reference pages.
Django Integration
Exact reference for include_routes and Django URL wiring.
Settings
Exact reference for HYPER_FRONTEND_DIR, HYPER_VITE_OUTPUT_DIR, HYPER_VITE_DEV_SERVER_URL, and HYPER_DEV.
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.
Client Runtime
Detailed reference for $action, window.action, runtime outcomes, and browser events.
HTML APIs
Reference for hyper-form-disable, hyper-view-transition-name, and loading-related attributes.
Template Tags
Reference for hyper_preloads, hyper_stylesheets, hyper_head_scripts, hyper_body_scripts, and hyper_custom_entry.
Commands
Reference for hyper_scaffold and hyper_routes.