shrd 0.3.0

A Django-native component framework with props, state, HTMX, and Alpine.js

Shard

A Django-native component framework for building UI with props, server state, slots, and scoped styles — using only the Django ecosystem plus bundled HTMX and Alpine.js.

📖 Full documentation

Shard is a framework, not a drop-in library. Your Django project adopts its conventions: components live in your apps, templates sit beside scoped CSS, and HTMX carries server actions.

Philosophy

Shard does not ship a widget catalog. It gives you a small, familiar model — closer to React/Vue than to Django templates alone — without a build step or SPA complexity:

• Props — typed inputs declared on a Python class
• State — server-owned data updated via @action methods
• Slots — wrap and compose markup like children / default slots
• Scoped styles — co-located .css files, automatically prefixed to the component
• Computed — derived values via @computed methods
• Events — HTMX custom events via @emits and ActionResult
• HTMX — partial re-renders after actions
• Alpine.js — optional client-side behavior inside templates
• View data — optional structured layouts, mutable via ViewTreeComponent

Quick start

# myapp/components.py
from shard import Component, Prop, action

class Card(Component):
    title = Prop(str, default="")
    template_name = "components/card.html"

{% load shard %}
{% shard_scripts %}

{% component Card title="Profile" %}
  <p>Anything here is passed through the default slot.</p>
{% endcomponent %}

See the quickstart guide for a full walkthrough.

Documentation

Topic	Link
Installation	getting-started/installation
Components	concepts/components
Slots	concepts/slots
Scoped styles	concepts/styles
Actions & HTMX	interactivity/actions
HTMX & Alpine	guides/htmx-and-alpine
View data	guides/view-data
API reference	reference/api
Examples	examples

Example app

pip install shrd[dev]
cd example
python manage.py migrate
python manage.py runserver

Or install from source:

pip install -e ".[dev]"
cd example
python manage.py migrate
python manage.py runserver

Development

pip install -e ".[dev]"
pre-commit install
python -m pytest tests/ -q
python manage.py shard_report   # framework size / page-load weight

96 tests with ≥90% coverage. CI runs pre-commit, Ruff, tests (Python 3.10–3.12), and docs build on every PR.

pre-commit run --all-files  # lint + format locally
pip install -e ".[docs]"
python -m mkdocs serve

License

MIT