How to Create a Django Tailwind Web App

Tailwind CSS currently does not have documentation on how to integrate the Tailwind CSS download with a Django project. 

Luckily there is a package designed for this exact integration. 

Note: I'll name my environment, project, and app env, project, and app to keep things simple. 

Install Node.js and npm

First, install Node.js and npm if you don't have them already.

Both install together using the Node installer. 

Select the installer that's right for your operating system then download the file. 

Node.js install on Windows

Wait for the download to finish, then run the "Node.js Setup Wizard" for Windows.

Node.js install on macOS

If you are on a macOS, wait for the download and complete the "Install Node.js" install process. 

Python virtual environment

Create a virtual environment for your Tailwind Django project

Command Line (Windows)

C:\Users\Owner> cd desktop
C:\Users\Owner\desktop> py -m venv env

As always, create a Python virtual environment.

I'll call it env.

Activate the environment

Command Line (Windows)

C:\Users\Owner\desktop\> cd env
C:\Users\Owner\desktop\env> Scripts\activate
(env)C:\Users\Owner\desktop\env>

Enter the virtual environment.

Activate the environment before continuing. 

The command is Scripts\activate for Windows and source bin/activate for macOS.

Django installation

Install the Django Web Framework

Command Line (Windows)

(env)C:\Users\Owner\desktop\env>pip install django

Install django via the command line.  The command is pip install django.

Create a Django project

Command Line (Windows)

(env)C:\Users\Owner\desktop\env> django-admin startproject project

Now create the Django project. I named my project project.

The command is django-admin startproject project. 

Enter into the Django project via the command line

Command Line (Windows)

(env)C:\Users\Owner\desktop\env> cd project
(env)C:\Users\Owner\desktop\env\project>

Enter into the new project directory. 

Django-Tailwind installation

Install django-tailwind

Command Line

(env)C:\Users\Owner\desktop\env\project>pip install django-tailwind

django-tailwind is a package that integrates the Tailwind CSS framework with Django. Created by Tim Kamanin, this package makes the integration process simple.

Install the package with the command pip install django-tailwind. 

Add Tailwind to the installed apps

(env) > project > project > settings.py

...
# SECURITY WARNING: don't run with debug turned on in production!
DEBUG = True

ALLOWED_HOSTS = []


# Application definition

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'tailwind',
]
...

Add tailwind to the list of INSTALLED_APPS in the Django settings.py file. 

Create a Tailwind + Django App

Create a Tailwind CSS Django App

Command Prompt (Windows)

(env)C:\Users\Owner\desktop\env\project>py manage.py tailwind init app

It's time to create a Tailwind-compatible Django app!

Run the command py manage.py tailwind init app to create an app called app in your Django project.

Add Tailwind to the installed apps

(env) > project > project > settings.py

...
# SECURITY WARNING: don't run with debug turned on in production!
DEBUG = True

ALLOWED_HOSTS = []


# Application definition

INSTALLED_APPS = [
    'main.apps.MainConfig',
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'tailwind',
    'app',
]
...

Return back to the settings.py and list app to the list of INSTALLED_APPS. 

Register the Tailwind-Django app

(env) > project > project > settings.py

...
# SECURITY WARNING: don't run with debug turned on in production!
DEBUG = True

ALLOWED_HOSTS = []


# Application definition

INSTALLED_APPS = [
    'main.apps.MainConfig',
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'tailwind',
    'app',
]

TAILWIND_APP_NAME = 'app'
...

Register your Tailwind-Django app in the settings.py file with the string TAILWIND_APP_NAME ='app'. 

Install Tailwind CSS dependencies

Command Prompt (Windows)

(env)C:\Users\Owner\desktop\env\project>py manage.py tailwind install

Install the Tailwind CSS dependencies with the command py manage.py tailwind install.

Error when installing Tailwind CSS dependencies?

Python executable may have a problem finding npm on Windows systems. Solve this problem by setting the executable path in the settings.py file.  

First, run the command which npm to get the path.

Command Prompt (Windows)

(env)C:\Users\Owner\desktop\env\project>which npm
/c/Program Files/nodejs/npm

(env) > project > project > settings.py

...
# SECURITY WARNING: don't run with debug turned on in production!
DEBUG = True

ALLOWED_HOSTS = []


# Application definition

INSTALLED_APPS = [
    'main.apps.MainConfig',
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'tailwind',
    'app',
]

TAILWIND_APP_NAME = 'app'

NPM_BIN_PATH = r"C:\Program Files\nodejs\npm.cmd"
...

Then add the path to the settings.py.

The path may be different for each system so be sure to run the command above rather than guessing.

The path above works for Windows.

Command Prompt (Windows)

(env)C:\Users\Owner\desktop\env\project>py manage.py tailwind install

Now you can install the Tailwind CSS dependencies.

Create the main Django app

Create a Django app named main

Command Prompt (Windows)

(env)C:\Users\Owner\desktop\env\project>py manage.py startapp main

Create a main app with the command py manage.py startapp main. 

Make Django's initial migrations

Command Prompt (Windows)

(env)C:\Users\Owner\desktop\env\project>py manage.py migrate

Run the command py manage.py migrate to run all of the initial migrations preset by the Django framework.

Add the main app to the settings

(env) > project > project > settings.py

...
# SECURITY WARNING: don't run with debug turned on in production!
DEBUG = True

ALLOWED_HOSTS = []


# Application definition

INSTALLED_APPS = [
    'main.apps.MainConfig',
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'tailwind',
    'app',
    'main',
]

TAILWIND_APP_NAME = 'app'

NPM_BIN_PATH = r"C:\Program Files\nodejs\npm.cmd"
...

Add main to the INSTALLED_APPS list in the settings.py.

Create the main app URLs

(env) > project > main > (New File) urls.py

from django.urls import path
from . import views

app_name = "main"   


urlpatterns = [
    path("", views.homepage, name="homepage"),
]

Create a new file called urls.py in the project > main directory. Add the app name and a URL path to a homepage I'll make in a minute. 

Create the homepage view

(env) > project > main > views.py

from django.shortcuts import render

# Create your views here.
def homepage(request):
	return render(request = request, template_name="main/home.html")

Add a homepage view that returns the template main/home.html.

Add the main homepage template

(env) > project >main > (New Folder) templates > (New Folder) main > (New File) home.html

<!DOCTYPE html>
<html>
  <head>
    <!-- Required meta tags -->
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Title</title>
  </head>
  <body>
    <h1>Django + Tailwind</h1> 
      
  </body>
</html>

Create a templates folder in the main directory. Then create a home.html file in the new templates folder.

Connect the main URLs to the project URLs

(env) > project > project > urls.py

"""mysite URL Configuration

The `urlpatterns` list routes URLs to views. For more information please see:
    https://docs.djangoproject.com/en/2.1/topics/http/urls/
Examples:
Function views
    1. Add an import:  from my_app import views
    2. Add a URL to urlpatterns:  path('', views.home, name='home')
Class-based views
    1. Add an import:  from other_app.views import Home
    2. Add a URL to urlpatterns:  path('', Home.as_view(), name='home')
Including another URLconf
    1. Import the include() function: from django.urls import include, path
    2. Add a URL to urlpatterns:  path('blog/', include('blog.urls'))
"""
from django.contrib import admin
from django.urls import path, include  #add include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include ('main.urls')),   #add this
]

Add the main URLs as a path in the project urls.py. That way the projects have access to the main URL paths. 

Run the Django server

Command Prompt (Windows)

(env)C:\Users\Owner\desktop\env\project>py manage.py runserver

Run the development server and you'll see the "Django + Tailwind" written on the home.html. 

Connect Django-Tailwind stylesheet to Django main app

Add the Tailwind Stylesheet to the HTML template

(env) > project >main > templates > main > home.html

{% load static %}
<!DOCTYPE html>
<html lang="en">

	<head>
		<meta charset="UTF-8">
		<meta name="viewport" content="width=device-width, initial-scale=1.0">
		<meta http-equiv="X-UA-Compatible" content="ie=edge">
		<title>Tailwind CSS Skeleton</title>
		<meta name="description" content="">
		<meta name="keywords" content="">
		<meta name="author" content="">

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

	<body class="bg-grey-lightest font-serif leading-normal tracking-normal">

		<div class="container mx-auto">
			<section class="flex items-center justify-center h-screen">
				<h1 class="text-5xl">Django + Tailwind = ❤️</h1>
			</section>

		</div>


	</body>

</html>

Look in the app > templates directory and find the base.html. Copy and paste this HTML code in your Django home.html template.

Start Tailwind in developer mode

Command Prompt (Windows)

(env)C:\Users\Owner\desktop\env\project>py manage.py tailwind start

Start the web app by running the command py manage.py tailwind start. 

Wait for the app to render and the Tailwind stylesheet to generate. 

Every time you edit the SCSS file, the stylesheet needs to be regenerated using this command.

View Django Tailwind Template

Reload the browser page and the Tailwind SCSS is applied to the template.

Configure the Tailwind Stylesheet

Update the SCSS file

(env) > project > app > static_src > src > styles.scss

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

Find the SCSS file in the app > static_src > src directory. This is the file to update to customize the Tailwind CSS. 

This file only needs to change if you're customizing components and class attribute values.