Django Tailwind
Updated
Table of Contents
This tutorial demonstrates how to configure Django and TailwindCSS from scratch in a new project.
Django Setup
Create a new virtual environment called .venv
.
# Windows
$ python -m venv .venv
$ .venv\Scripts\Activate.ps1
(.venv) $
# macOS/Linux
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $
Then install Django and create a new project called django_project
.
(.venv) $ python -m pip install django
(.venv) $ django-admin startproject django_project .
Make a project-level templates
directory from the command line using the mkdir
command.
(.venv) $ mkdir templates
We will store our templates here rather than within each app. However, we need to tell Django where to find them by updating the TEMPLATES
configuration in settings.py
.
# django_project/settings.py
TEMPLATES = [
{
...
"DIRS": [BASE_DIR/"templates"], # new
...
}
]
Create a templates/base.html
file.
<!-- templates/base.html -->
<h1>Hello, World</h1>
If we cleverly use ' django_project/urls.py ', we can include the view and URLs in one file. Import TemplateView
at the top and then set a path that points to the template, base.html
.
# django_project/urls.py
from django.contrib import admin
from django.urls import path
from django.views.generic import TemplateView # new
urlpatterns = [
path("admin/", admin.site.urls),
path("", TemplateView.as_view(template_name="base.html"),), # new
]
Use the runserver
command to confirm the homepage is working.
(.venv) $ python manage.py runserver
Tailwind Configuration
The Tailwind docs have an installation guide we can follow with only a few changes. Open a new terminal session from the project directory: we will ultimately need to have two running, one with our Django server and one with Node.
In the new terminal window, make sure you have Node installed on your computer. You can check with node-v
.
$ node -v
v20.17.0
Create a package.json
file to use Node and Tailwind together. Add the -y
flag to say yes to all defaults.
$ npm init -y
This is the resulting package.json
file.
{
"name": "django-tailwind",
"version": "1.0.0",
"description": "How to configure Django and Tailwind from scratch in a new project.",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}
Install Tailwind via npm
.
$ npm install -D tailwindcss
This creates a node_modules
directory. Next create a tailwind.config.js
file.
$ npx tailwindcss init
Created Tailwind CSS config file: tailwind.config.js
Now we have a tailwind.config.js
file. Add paths to it for our templates directory.
// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ["./templates/**/"], // updated line here!
theme: {
extend: {},
},
plugins: [],
}
In the Django project, create a static
directory and a subdirectory called src
.
$ mkdir static
$ mkdir static/src
We need to tell Django to look here for files by updating the STATICFILES_DIRS
configuration.
# settings.py
STATICFILES_DIRS = [BASE_DIR / "static",] # new
Then create a new CSS file called static/src/styles.css
and add @tailwind
directives to it.
/* static/src/styles.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
The next step is to start the Tailwind CLI build process. It will scan our template files for classes and build the necessary CSS. We've changed the paths from the Tailwind website slightly here so that it looks in the src/styles.css
file and outputs to dist/styles.css
.
$ npx tailwindcss -i ./static/src/styles.css -o ./static/dist/styles.css --watch
To try it out, update the base.html
template file with some Tailwind classes. It's important to add the load static
tag at the top and also link to the new stylesheet. Then, we add basic classes to make the title red and the text below blue.
<!-- templates/base.html -->
{% load static %}
<link href="{% static 'dist/styles.css' %}" rel="stylesheet">
<h1 class="text-red-600">Hello, World</h1>
<p class="text-blue-600">More text</p>
Hard refresh the homepage.
You can see the updates to the text indicating that Tailwind is properly installed.
watch:css Script
We have a basic installation up and running, but you'll soon find that a few extra features improve things significantly.
First, we don't want to remember that big, long command to have Node running. We can put it inside the package.json file as a script that starts with "watch:css."
// package.json
{
"name": "django-tailwind",
"version": "1.0.0",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"watch:css": "npx tailwindcss -i ./static/src/styles.css -o ./static/dist/styles.css --watch"
},
"keywords": [],
"author": "",
"license": "ISC",
"description": "",
"devDependencies": {
"tailwindcss": "^3.4.10"
}
}
In the terminal where Node is running, stop it with Ctrl+c
. Type in npm run watch:css
and it should start as before.
$ npm run watch:css
Refresh the webpage to make sure everything still works.
Conclusion
As we've seen, Tailwind works well with Django. For extra goodies, check out django-browser-reload to automatically reload your browser in development so you don't have to do hard refreshes all the time. There is also a well-maintained third-party package, django-tailwind, which provides another approach to integrating Tailwind with Django.