Django Tailwind

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.