Django and Tailwind integration

Following is a step by step guide on how to integrate Tailwind in Django projects. There are many ways to do it but I find this to be the easiest. This method requires Bun (a javascript runtime) as a prerequisite. Alternatively you can also use Node.js (another javascript runtime) and npm(node package manager). I prefer Bun as it does not require a separate package manager like npm in case of Node.

Before starting let me mention that there is a package called django-tailwind for this same purpose. But I prefer the current approach because I find the setup for django-tailwind very complex. (django-tailwind also requires Node.js)

Now, let’s start.

Go to the root of the Django project.

Install Bun if it is not installed already. Installation is very easy for any operating system.

Install Tailwind.

bun i tailwindcss

This will automatically create two files, package.json and bun.lockb, in the current directory.

Create the Tailwind config file.

bunx tailwindcss init

This will create tailwind.config.mjs file. The file looks like this:

module.exports = {
  content: [],
  theme: {
    extend: {}
  },
  plugins: []
}

Replace content: [] with content: ["./templates/**/*.html"] so that the file looks like this:

module.exports = {
  content: ["./templates/**/*.html"],
  theme: {
    extend: {}
  },
  plugins: []
}

This guide assumes that your templates directory is at the root level of your project. If it is somewhere else, you may need to change content accordingly.

Configuration is done, now we need to create the css files. I like to put css files inside static/css dir, however you can put them anywhere inside the static dir.

Create two files, input.css and output.css inside static/css.

Paste the followind inside input.css

@tailwind base;
@tailwind components;
@tailwind utilities;

output.css is the file that will contain all the styles generated by Tailwind. Include the output.css in your base Django template by putting the following line anywhere between <head> and </head>.

<link rel="stylesheet" href="{% static 'css/output.css' %}" />

Also remember to add the {% load static %} tag at the top of your base Django template.

Finally we need to run a process that watches for any changes in Django templates and input.css and automatically generates the output styles in output.css. To do so, run the following command.

bunx tailwindcss -i ./static/css/input.css -o ./static/css/output.css --watch

This process should keep running during the development. This is not needed while running in production as the output.css is already generated during development.

The integration is complete, now you can use the Tailwind classes in your project.

However for a better development experience, I suggest the following:

Install django-browser-reload so that your browser reloads automatically whenever you make any changes to the templates. (This package is helpful even when you do not have Tailwind)
Instead of running the dev server and the Tailwind watch process separately, I prefer to use the following script.

import subprocess
import threading

def run_server():
    subprocess.run(f"venv/bin/python3 manage.py runserver", shell=True)

def run_tailwind():
    subprocess.run(
        "bunx tailwindcss -i ./static/css/input.css -o ./static/css/output.css --watch",
        shell=True,
    )

threading.Thread(target=run_server).start()
threading.Thread(target=run_tailwind).start()

You can use this script or a modified version of this script to start your dev server along with the Tailwind watch process.