Installation

Requirements

• Python 3.10+
• Django 4.2+

Install from PyPI

pip install shrd

Requires Python 3.10+ and Django 4.2+. The import name is shard:

INSTALLED_APPS = ["shard", ...]

Install from source

git clone https://github.com/kurtisrogers/Shard.git
cd Shard
pip install -e .

Development install

Includes pytest for running the test suite:

pip install -e ".[dev]"

Add to a Django project

# settings.py
INSTALLED_APPS = [
    # ...
    "shard",
    "myapp",  # your app with components.py
]

urlpatterns = [
    # ...
    path("shard/", include("shard.urls")),
]

Optional context processor

Expose framework metadata in every template:

TEMPLATES = [{
    "OPTIONS": {
        "context_processors": [
            # ...
            "shard.context_processors.shard",
        ],
    },
}]

This adds a SHARD dict with version, url_namespace, and debug.

Static files

Shrd bundles HTMX and Alpine.js. Load them once per page:

{% load shard %}
{% shard_scripts %}

In production, run collectstatic as usual. Shrd assets live under shard/static/shard/.

Cache backend

Component state (props, slots, server state) is stored in Django's cache framework. Configure any cache backend:

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
    }
}

For development, LocMemCache works fine.

Testing your project

Shrd components are plain Django Python classes — test them with pytest and pytest-django:

pip install pytest pytest-django

See the Testing guide for a settings checklist, conftest.py examples, and patterns for mount(), action logic, and HTMX requests.

Documentation site

Published docs: kurtisrogers.github.io/Shard

The Deploy documentation workflow (.github/workflows/docs.yml) builds MkDocs and deploys via GitHub Actions on every push to main. In Settings → Pages, set the source to GitHub Actions (not the gh-pages branch).

Build locally:

pip install -e ".[docs]"
python -m mkdocs serve