Installation and Setup

Requirements

Python 3.8 or newer
Django 4.2, 5.2, or 6.0

djxi has no dependencies beyond Django itself. asgiref (bundled with Django) is used by the async rendering helper.

Installation

pip install djxi

INSTALLED_APPS

Add "djxi" to INSTALLED_APPS to enable the bundled templates and template tags:

INSTALLED_APPS = [
    # ...
    "djxi",
]

This is required for {% load djxi %} and the built-in message templates to work.

Middleware (recommended)

Add DjxiHeadersMiddleware to attach request.htmx and response.htmx helpers:

MIDDLEWARE = [
    # ... Django built-in middleware ...
    "djxi.middleware.DjxiHeadersMiddleware",
]

Place it after SessionMiddleware and MessageMiddleware so that session and message storage are available when the htmx helper is initialised.

Base template

Use the bundled template tags in your project’s base template:

{% load djxi %}
<!doctype html>
<html>
  <head>
    {% htmx_script_inclusion %}   {# loads HTMX from CDN #}
  </head>
  <body {% htmx_headers %}>        {# adds hx-headers with CSRF token #}
    {% flash_messages_inclusion %} {# OOB message target container #}
    {% block content %}{% endblock %}
  </body>
</html>

htmx_script_inclusion loads the HTMX version configured by DX_HTMX_VERSION (default "4") from jsDelivr CDN with a SRI integrity hash. For production you will likely want to self-host HTMX via your staticfiles pipeline instead.

Running the included example

A full Django example project is included in the repository under example/:

cd example
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

Visit http://127.0.0.1:8000/ to explore the Todo app and showcase batteries.

Notes

The example app (example/todo/views.py) demonstrates a full CRUD DXEndpointBattery with list rendering, inline editing, state toggling, and deletion.
The bundled message templates in djxi/templates/djxi/messages/ can be overridden by placing templates with the same names in your project’s template directories.