A simple Django starterkit with Django, HTMX and Hyperscript.
This project is just a basic todo list.
However, it is made using a combination of Django, HTMX and Hyperscript and shows how you can get the reactivity of a frontend JS framework without sacrificing the benefits of your server-side framework (session authentication, templating, etc).
- ✔️ Supports latest Python 3.12
- ✔️ Poetry for managing dependencies.
- ✔️ Django (latest version 5).
- ✔️ HTMX to build modern and reactive user interfaces without the complexity of a JS frontend framework.
- ✔️ Hyperscript is a Javascript library as an companion to HTMX to compose behavior directly in HMTL.
- ✔️ Tailwindcss a utility-first CSS framework for styling.
- ✔️ DaisyUI a Tailwind component library.
- ✔️ django-allauth for user authentication, registration and account management.
- ✔️ django-split-settings to organize Django settings into multiple files and directories. ✔️ - Support for multiple environments (e.g. development or production).
- ✔️ python-decouple to decouple config from and loading env variables and
.env
files. - ✔️ mypy and django-stubs for static typing.
- ✔️ pytest and hypothesis for unit tests.
- ✔️ ruff for code linting and formatting (replaces flake8, black and isort).
- ✔️ Docker support using docker-compose configuration for local development (incl. Postgres).
- ✔️ No complex frontend build pipeline. Only
Postcss
is used for Tailwindcss. Frontend reacivity is handled with HTMX and Hyperscript. Both doesn't require a build step.
This guide describes how you can quickly setup the project for local development.
Minimum requirements: Python 3.10, pip, pdm, & PostgreSQL (installed via docker), setup is tested on Mac OSX only.
The steps below will get you up and running with a local development environment. All of these commands assume you are at the root of your generated project.
- Install Python and PDM.
- Install NodeJS and Yarn.
Docker
; if you don’t have it yet, follow the installation instructions.Docker Compose
; refer to the official documentation for the installation guide.
To install Python, PDM, NodeJS and Yarn run the following command on Mac OS:
brew install python3 pdm node yarn
For installing Docker and docker-compose refer to the official documentation.
git clone https://github.com/hypebeast/django-htmx-starterkit
Before you can start the project you need to set some environment variables. This can be done via creating an .env
file:
cp .env.template .env
Now open the .env
file and add the required configuration.
Here is an example with the minimum required config:
DOMAIN_NAME=localhost
DJANGO_SECRET_KEY=<yoursecretekey>
POSTGRES_DB=starterkit
POSTGRES_USER=starterkit
POSTGRES_PASSWORD=password
DJANGO_DATABASE_HOST=localhost
DJANGO_DATABASE_PORT=5432
Generate the secret key with:
python3 -c 'from django.utils.crypto import get_random_string; print(get_random_string(50))'
Build all docker-compose services with:
docker compose build
Run the database with the following command:
docker compose up -d
Install all dependencies with PDM:
make install
Run the migrations with:
make migrate
The frontend project is located in the themes
app. This Django app handles the This is required because of TailwindCSS.
Install the dependencies:
make frontend-install
Now, you can start the frontend dev server with the following command:
make frontend-dev
Now, you can start the development server with the following command:
make dev
Now you can open the site: Homepgae.
Some useful commands:
make run
- start django servermake test
- run the test locally with ipdb
Note: Run make help
to see a list with all available commands.
NOTE: Checkout Makefile for all the options available and how they do it.
├── apps
│ ├── accounts
│ │ ├── migrations
│ │ └── templates
│ ├── core
│ ├── main
│ │ ├── logic
│ │ ├── migrations
│ │ └── templates
│ ├── tasks
│ │ ├── migrations
│ │ └── templates
│ └── theme
│ ├── migrations
│ ├── static
│ ├── templates
│ └── templatetags
├── config
│ └── settings
│ ├── components
│ └── environments
└── docker
├── caddy
├── django
└── frontend
For managing the dependencies PDM is used. PDM, is a modern Python package and dependency manager supporting the latest PEP standards. But it also helps you with your development worklfow and boosts your development workflow in various aspects.
Please, refere to the PDM Documentation for more information.
Install all dependecies:
pdm sync
Add a new package
pdm add <packagename>
Create a virtualenv
:
pdm venv create 3.10
pdm venv activate # Copy the printed command and run it to activate the virtualenv
TODO: Add description for how to configure the application.
TODO: Add description how to work with the frontend code.
TODO: Add instructions for deployment on fly.io
.
- Add tests
- Add support for production deployment
- black
- mypy & django-stubs
The MIT License (MIT). See the LICENSE for more information.
Copyright 2024 Sebastian Ruml sebastian.ruml@gmail.com.