Dans cet article, je vais vous montrer comment utiliser le package django-tailwind pour utiliser Tailwind CSS à l'intérieur d'un projet Django.
Dans la suite de cet article, je vais créer un projet Django en partant de 0 et vous montrer toutes les étapes nécessaires pour pouvoir utiliser Tailwind CSS. Vous pouvez partir d'un nouveau projet ou d'un projet déjà existant, les étapes seront les mêmes.
À la fin de l'article, je vous parlerai également des options de purge et comment éviter les erreurs les plus courantes rencontrées lors de l'utilisation de Tailwind avec Django.
Configuration de l'environnement
Pour cette application, j'utilise Python 3.9, Django 3.2.6 ainsi que Node JS, qui est nécessaire pour télécharger les packages JavaScript à l'aide de l'utilitaire npm (l'équivalent de pip pour JavaScript).
Je commence par créer un dossier et un environnement virtuel sur mon disque dur :
mkdir django-tailwind && cd django-tailwind
python3.9 -m venv env
source env/bin/activate
pip install django==3.2.6
Pour utiliser Tailwind CSS à l'intérieur de notre projet, nous allons utiliser le package django-tailwind. Au moment où j'écris cet article, la dernière version disponible est la 2.2.0 :
pip install django-tailwind==2.2.0
Je crée ensuite un projet Django à l'intérieur du dossier de mon projet :
django-admin startproject website
Une fois le projet créé, vous pouvez vérifier que tout fonctionne correctement en utilisant la commande runserver :
python manage.py runserver
Vous devriez voir la page d'accueil de Django :
Créer l'application pour tailwind
Pour pouvoir utiliser Tailwind CSS dans notre projet Django, nous allons devoir créer une application spécifique qui contiendra tous les fichiers de configuration et les feuilles de style de Tailwind.
Toutes les indications de cette partie sont tirées directement de la documentation officielle du package django-tailwind.
La première chose à faire est d'ajouter l'application 'tailwind' dans le fichier settings.py :
# settings.py
INSTALLED_APPS = [
# other Django apps
'tailwind',
]
Vous devez ensuite créer l'application qui contiendra tous les fichiers pour faire fonctionner tailwind :
python manage.py tailwind init
Le processus d'installation va vous demander le nom de l'application. Par défaut le nom 'theme' est utilisé.
À moins d'avoir déjà dans votre projet une application avec ce nom, je vous conseille de laisser ce nom par défaut.
Vous pouvez ensuite choisir entre les options Just in Time (jit) et Ahead of Time (aot).
L'option Just in Time, bien que plus récente et encore en phase expérimentale, est le mode conseillé pour avoir la meilleure expérience de développement.
Avec ce mode, votre fichier CSS sera construit automatiquement à partir des classes que vous utilisez et aura une taille optimale.
Une fois la création de l'application 'theme' terminée, il faut également l'ajouter dans le fichier settings.py :
# settings.py
INSTALLED_APPS = [
# other Django apps
'tailwind',
'theme'
]
Il faut également ajouter dans votre fichier settings.py le nom de l'application dans la variable TAILWIND_APP_NAME.
Bien entendu, si vous avez choisi un autre nom pour l'application, il faut utiliser ce nom à la place de 'theme'.
# settings.py
TAILWIND_APP_NAME = 'theme'
Afin de permettre le rafraîchissement automatique de votre page web quand vous êtes en développement (avec l'option DEBUG=True), vous devez également rajouter votre adresse IP locale dans la variable INTERNAL_IPS à l'intérieur du fichier settings.py :
# settings.py
INTERNAL_IPS = [
"127.0.0.1",
]
Pour finir, il faut installer toutes les dépendances JavaScript nécessaire avec la commande :
python manage.py tailwind install
Ce processus peut prendre quelques minutes et nécessite Node JS et npm. Assurez-vous au préalable d'avoir installé Node JS.
Une fois l'installation terminée, il ne reste plus qu'à inclure la feuille de style de Tailwind dans vos fichiers de gabarits.
Pour ce faire il faut déjà charger les tailwind_tags avec {% load tailwind_tags %}. Les feuilles de style peuvent ensuite être intégrées à l'intérieur de la balise head de votre fichier HTML avec la balise {% tailwind_css %} :
# Fichier HTML de votre projet Django
{% load tailwind_tags %}
...
...
{% tailwind_css %}
...
Si vous utilisez l'héritage de gabarit, je vous conseille de mettre ces balises dans votre fichier de base dont vont hériter tous vos gabarits.
Vous n'aurez ainsi pas à ajouter manuellement ces tags à l'intérieur de chaque fichier HTML.
Vous trouverez plus d'informations sur l'héritage de gabarits ici, ou dans la documentation officielle de Django.Il ne vous reste plus qu'à lancer le serveur de développement de tailwind qui va s'assurer de créer automatiquement le fichier CSS à chaque fois que vous modifiez vos fichiers de gabarit :
python manage.py tailwind start
Ce processus est très rapide, normalement autour de 30ms.
Plus vous aurez de fichiers HTML dans votre projet, plus ce processus prendra un peu de temps, mais même sur Docstring, qui contient des centaines de fichiers HTML, je n'ai jamais dépassé les 600ms, ce qui reste très rapide.
Le principe de 'purge'Afin de minimiser la taille du fichier CSS à charger dans votre projet, tailwind dispose d'un processus de 'purge' qui ne va garder dans la feuille de style finale que les classes que vous utilisez.
Par défaut, seuls les fichiers HTML à l'intérieur des différents dossiers de templates de Django sont pris en compte.
Heureusement, il est possible de modifier cette configuration en modifiant la clé 'purge' dans le fichier tailwind.config.js qui se trouve dans l'application theme à l'intérieur du dossier static_src :
/* theme/static_src/tailwind.config.js */
purge: [
/**
* HTML. Paths to Django template files that will contain Tailwind CSS classes.
*/
/* Templates within theme app (/templates), e.g. base.html. */
'../templates/**/*.html',
/*
* Main templates directory of the project (BASE_DIR/templates).
* Adjust the following line to match your project structure.
*/
'../../templates/**/*.html',
/*
* Templates in other django apps (BASE_DIR//templates).
* Adjust the following line to match your project structure.
*/
'../../**/templates/**/*.html',
/**
* JS: If you use Tailwind CSS in JavaScript, uncomment the following lines and make sure
* patterns match your project structure.
*/
/* JS 1: Ignore any JavaScript in node_modules folder. */
// '!../../**/node_modules',
/* JS 2: Process all JavaScript files in the project. */
// '../../**/*.js',
/**
* Python: If you use Tailwind CSS classes in Python, uncomment the following line
* and make sure the pattern below matches your project structure.
*/
// '../../**/*.py'
],
Par défaut, vous remarquez que seuls les fichiers HTML à l'intérieur des dossiers templates sont pris en compte.
Si jamais vous utilisez des classes tailwind à l'intérieur d'un fichier JavaScript ou d'un fichier Python par exemple, n'oubliez pas d'enlever les commentaires sur les lignes correspondantes :
'../../**/*.js' et '../../**/*.py'
Erreurs courantes
❌ Ma classe n'est pas reconnue
Assurez-vous de lancer le serveur de développement de tailwind avec la commande python manage.py tailwind start. C'est ce serveur qui va scanner tous les fichiers de votre projet pour vérifier quelle classe de Tailwind vous utilisez et les ajouter au fichier CSS final. Ce processus est réalisé pour éviter de charger l'intégralité des classes de Tailwind CSS dans votre projet.
Assurez-vous également comme nous l'avons vu ci-dessus, de modifier le fichier de purge si jamais vous utilisez des classes Tailwind dans des fichiers JavaScript ou Python.
❌ Mon site n'est pas mis à jour automatiquement
Le package django-tailwind inclut par défaut l'extension browsersync qui s'assure de rafraîchir automatiquement votre site web lorsqu'un changement est détecté dans un fichier. Si vous utilisez PyCharm, qui sauvegarde automatiquement en arrière-plan vos fichiers, il se peut que vous ayez besoin de mettre la fenêtre de votre navigateur en avant-plan pour forcer le rafraîchissement de la page. Pour éviter d'avoir à changer tout le temps entre PyCharm et votre navigateur web, vous pouvez forcer la sauvegarde de vos fichiers dans PyCharm avec Ctrl + S (Cmd + S sur Mac).