A modern, secure, and production-ready Django package for seamless integration with Alpine.js and its official plugins.
- 🚀 Zero-Configuration Offline Support: Ships with pre-packaged, minified Alpine.js (
v3.16.3) and all 8 official plugins. - 📦 Namespaced Static Assets: Static files are safely stored under
django_alpine/to avoid naming collisions with your project files. - 🧩 First-Class Plugin Support: Easily include official plugins (
collapse,focus,intersect,mask,morph,persist,sort,anchor) with automatic, dependency-compliant script ordering. - 🛡️ Security & CSP Ready: Native Content Security Policy (CSP) nonce support (manual and auto-detected with
django-csp). - 🌐 CDN / Local Toggle: Switch effortlessly between local offline assets and CDN delivery per-template or globally via
settings.py. - ⚡ Built-in Management Command: Update Alpine.js and plugins anytime using
python manage.py download_alpine. - 🧪 Fully Tested: High-coverage test suite across supported Python (3.10 to 3.14+) and Django (4.2+ LTS, 5.x) versions.
Install django-alpine using pip:
pip install django-alpineAdd django_alpine to your INSTALLED_APPS in settings.py:
INSTALLED_APPS = [
# ...
"django_alpine",
]Load the template tags and use {% alpine_script %} in your base template:
{% load alpine_tags %}
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>My Django Project</title>
<!-- Injects Alpine.js core script with defer -->
{% alpine_script %}
</head>
<body>
<div x-data="{ count: 0 }">
<button @click="count++">Increment</button>
<span x-text="count"></span>
</div>
</body>
</html>Rendered HTML:
<script src="/static/django_alpine/alpine.min.js" defer></script>Official plugins require loading before Alpine core. django-alpine automatically handles the proper ordering for you:
{% load alpine_tags %}
<head>
{% alpine_script plugins="collapse,focus,intersect" %}
</head>Rendered HTML:
<script src="/static/django_alpine/plugins/collapse.min.js" defer></script>
<script src="/static/django_alpine/plugins/focus.min.js" defer></script>
<script src="/static/django_alpine/plugins/intersect.min.js" defer></script>
<script src="/static/django_alpine/alpine.min.js" defer></script>anchor(@alpinejs/anchor)collapse(@alpinejs/collapse)focus(@alpinejs/focus)intersect(@alpinejs/intersect)mask(@alpinejs/mask)morph(@alpinejs/morph)persist(@alpinejs/persist)sort(@alpinejs/sort)
Pass an explicit nonce or let django-alpine detect request.csp_nonce automatically:
{% load alpine_tags %}
<!-- Explicit Nonce -->
{% alpine_script nonce="your-csp-nonce" %}
<!-- Automatic Nonce (when request context is available) -->
{% alpine_script %}Rendered HTML:
<script src="/static/django_alpine/alpine.min.js" nonce="your-csp-nonce" defer></script>You can enable CDN mode directly in a template or globally in settings.py:
<!-- In template -->
{% alpine_script use_cdn=True plugins="collapse,focus" version="3.16.3" %}Or configure globally in settings.py:
# settings.py
ALPINE_USE_CDN = True # Default: False
ALPINE_VERSION = "3.16.3" # Default: "3.16.3"{% alpine_js %}: Alias for{% alpine_script %}(backward compatibility).{% alpine_url %}: Returns the raw URL path toalpine.min.js(useful for custom script loaders).
<script src="{% alpine_url %}" async></script>Update your bundled Alpine.js assets or download them into a custom project directory:
# Download latest version from NPM registry with all plugins
python manage.py download_alpine
# Download a specific version and select specific plugins
python manage.py download_alpine --alpine-version 3.16.3 --plugins collapse,focus
# Download without plugins
python manage.py download_alpine --plugins none
# Download to a custom directory
python manage.py download_alpine --output-dir ./static/vendor/alpine
# Dry-run mode (simulates download without writing files)
python manage.py download_alpine --dry-runAll settings are optional and have sensible defaults:
| Setting | Type | Default | Description |
|---|---|---|---|
ALPINE_USE_CDN |
bool |
False |
When True, script tags default to CDN URLs. |
ALPINE_VERSION |
str |
"3.16.3" |
Default Alpine version used for CDN URLs. |
ALPINE_CDN_URL |
str |
https://cdn.jsdelivr.net/npm/alpinejs@{version}/dist/cdn.min.js |
Custom CDN template for core script. |
ALPINE_PLUGIN_CDN_URL |
str |
https://cdn.jsdelivr.net/npm/@alpinejs/{plugin}@{version}/dist/cdn.min.js |
Custom CDN template for plugins. |
Run the test suite using the provided runner script in bin/:
./bin/test.shOr directly via Django:
python -m django test --settings=tests.settings testsThis project is licensed under the BSD 3-Clause License. See the LICENSE file for details.
- Anye Prince Kelly (@ProKelly) - Original Creator
- Jeremy LANE (@jeremylanes) - Lead Maintainer & Architect