How to use TailwindCSS with Django?
Django-Tailwind CSS is a very good package and it works well for me. Follow the docs properly and you will be fine.
Before you begin, make sure you have npm properly installed on your system
Quick start
- Install the python package django-tailwind from pip
pip install django-tailwind
Alternatively, you can download or clone this repo and run pip install -e ..
Add
tailwindto INSTALLED_APPS in settings.pyCreate a tailwind-compatible Django-app, I like to call it
theme:
python manage.py tailwind init theme
Add your newly created
themeapp to INSTALLED_APPS in settings.pyIn settings.py, register tailwind app by adding the following string:
TAILWIND_APP_NAME = 'theme'
- Run a command to install all necessary dependencies for tailwind css:
python manage.py tailwind install
- Now, go and start tailwind in dev mode:
python manage.py tailwind start
Django Tailwind comes with a simple base.html template that can be found under yourtailwindappname/templates/base.html. You can always extend it or delete it if you have own layout.
If you're not using base.html template provided with Django Tailwind, add styles.min.css to your own base.html template file:
You should now be able to use Tailwind CSS classes in your html.
To build a production version of CSS run:
python manage.py tailwind build
For the live reload, this handles it:
python manage.py tailwind start
For the build process, this handles it:
python manage.py tailwind build
For the PurgeCSS process, see simple sample in the docs
For NPM path configuration error (esp. on windows), see docs
Updated in July 2022: PostCSS is no longer necessary - there is a standalone CLI - django-browser-reload is the best extension - Django-tailwind plugin is an acceptable solution too.
There are (at least) 3 different methods to install Tailwind with Django properly.
1st method: NPM
This is the preferred method if you need node in your project (e.g : add plugins like Daisy UI, or have a SPA)
Installing tailwindCSS and build/minify processes
- Create a new directory within your Django project, in which you'll install tailwindCSS like in any vanilla JS project setup:
cd your-django-folder; mkdir jstoolchain; cd jstoolchain
npm init -y
npm install -D tailwindcss
npx tailwindcss init
- Configure your template paths in
tailwind.config.jsthat have just been created, by specifying the right place to parse your content. This could be something like below or a little different, depending on where your templates are located:
...
content: ["../templates/**/*.{html,js}"],
...
- In
your-django-folder, create aninput.cssfile and add at least this in it:
@tailwind base;
@tailwind components;
@tailwind utilities;
- In your
package.jsonfile, you can prepare npm scripts to ease execution of build / minify tasks (adapt the paths according to your Djangostaticfolder location):
"scripts": {
// use in local environment
"tailwind-watch": "tailwindcss -i ../input.css -o ../static/css/output.css --watch",
// use in remote environment
"tailwind-build": "tailwindcss -i ../input.css -o ../static/css/output.css --minify"
}
In your
jstoolchainsfolder, keep runningnpm run tailwind-watchwhile you're coding. This will ensure that youroutput.cssfile is regenerated as soon as you add a new tailwind class to your code. Add this file to.gitignore.If
tailwind-watchis running without error,output.cssfile should now be filled with CSS. Now you can actually use tailwindCSS classes, by including the outputted css file into a Django template file along with Django's call to load the static files:
{% load static %}
<head>
<link rel="stylesheet" href="{% static "css/output.css" %}">
</head>
- Don't forget to include the
npm run tailwind-buildscript in your deployment process. This will build the output and remove unused classes to ensure a lower file size.
Handling auto-reload locally
What's missing now to ease development, is to auto-reload the django development server when an HTML file is changed and saved. The best extension to deal with this is Django-browser-reload. Just follow setup instructions, this will work as expected out of the box
2nd method: standalone CLI
This is the preferred method if your project does not require node at all (eg: you don't have SPA for your front, you don't need plugins like daisyUI, etc.).
You can install it manually following the official instructions, or automate it using a script shell like this:
#!/bin/sh
set -e
TAILWIND_ARCHITECTURE=arm64 # chose the right architecture for you
TAILWIND_VERSION=v3.1.4 # chose the right version
SOURCE_NAME=tailwindcss-linux-${TAILWIND_ARCHITECTURE}
OUTPUT_NAME=tailwindcss
DOWNLOAD_URL=https://github.com/tailwindlabs/tailwindcss/releases/download/${TAILWIND_VERSION}/${SOURCE_NAME}
curl -sLO ${DOWNLOAD_URL} && chmod +x ${SOURCE_NAME}
mv ${SOURCE_NAME} ${OUTPUT_NAME} # rename it
mv ${OUTPUT_NAME} /usr/bin # move it to be used globally in a folder already in the PATH var
For Tailwind configuration itself, please refer to the 1st method where it's explained in detail.
3rd method: django-tailwind plugin
This plugin produces more or less the same results than you get manually with the npm method. The plugin is well documented, up to date, and people seem to be satisfied with it. As a personal preference, I think abstractions like this creates a little too magic and I prefer building the toolchain by myself to know what's happening behind the scene. But feel free to experiment this method as well and pick it if it suits you!