Integrating TailwindCSS into DjangoStarter

Preface

It's been a while since I last updated a technical article.

This month I've written quite a few unboxings and random notes, being busy and lazy at the same time.

I don't really feel like writing basic articles, and the slightly more in-depth ones take a lot of time to write.

Even though, in the end, I still want to pump out a quick post.

Recently, I worked on a project based on Wagtail, and there are quite a few things worth documenting. This article will start by recording how to add Tailwind CSS support to the DjangoStarter framework.

If you're using vanilla Django, you can also refer to this, as the process is mostly similar.

I previously saw a Python package called django-tailwind, but the bundled tailwind version might not be easy to update. Plus, DjangoStarter has been using NPM and Gulp to manage frontend static assets for a long time, so it's probably better to add Tailwind manually.

Installing tailwindcss

Installation

Run the command in the project root directory of DjangoStarter

pnpm install -D tailwindcss

Initialization

Execute the command in the root directory

npx tailwindcss init

This command will add a tailwind.config.js file to the root directory. Make some modifications:

/** @type {import('tailwindcss').Config} */
module.exports = {
    content: [
        './src/**/templates/**/*.html',
    ],
    theme: {
        extend: {},
    },
    plugins: [],
}

Create a CSS file

Create the file src/static/css/tailwind.src.css

Content

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

Start tailwind

Execute the command in the root directory.

npx tailwindcss -i .\src\static\css\tailwind.src.css -o .\src\static\css\tailwind.css --watch

That's it. During development, tailwindcss dynamically generates CSS files based on the classes used in the project.

Tailwind Component Libraries

The Tailwind ecosystem is quite rich, with many component library options to choose from. Even without a dedicated component library, you can search online for plenty of samples, including some with impressively designed interfaces. Now with tools like GPT, you can even have it write the UI code for you.

In my current projects, I'm using Flowbite and DaisyUI.

From actual use, I find Flowbite more comfortable. Its component style definitions are quite flexible, though you'll end up writing many classes.

DaisyUI, on the other hand, abstracts away many details of component definitions, making it relatively harder to customize styles.

For example:

Both are buttons.

Flowbite defines them like this:

<button type="button" class="text-white bg-blue-700 hover:bg-blue-800 focus:ring-4 focus:ring-blue-300 font-medium rounded-lg text-sm px-5 py-2.5 me-2 mb-2 dark:bg-blue-600 dark:hover:bg-blue-700 focus:outline-none dark:focus:ring-blue-800">Default</button>

DaisyUI uses a different approach, somewhat reminiscent of Bootstrap:

<button class="btn btn-primary">Primary</button>

Although DaisyUI's code is very concise, customizing it can be a bit troublesome.

Therefore, I prefer using the style approach similar to Flowbite. If components need to be reused frequently, I can then encapsulate them into my own components.

Using django-compressor to Compress Static Assets

django-compressor can compress and combine static files, enhancing the website's loading speed and performance.

Previously, we used gulp, a Node.js tool, to handle static assets, which included the functionality to compress them. Now, we delegate the compression step to django-compressor, which is more convenient.

Installation

pdm add django-compressor>=4.5

Register Service and Configuration

Modify src/config/settings/components/common.py

Add to INSTALLED_APPS:

INSTALLED_APPS = [
  # ...
  'compressor',
  # ...
]

Then configure STATICFILES_FINDERS

The settings.py created by the scaffold does not include this configuration. The first two finders are Django's defaults:

STATICFILES_FINDERS = [
  'django.contrib.staticfiles.finders.FileSystemFinder',
  'django.contrib.staticfiles.finders.AppDirectoriesFinder',
  'compressor.finders.CompressorFinder',
]

Create the src/config/settings/components/compressor.py file to separate the compressor configuration.

This library has many configuration options. For details, please refer to the official documentation. Here, I only enable the compression switch:

COMPRESS_ENABLED = True

Usage

OK, the usage is straightforward. Simply use the compressor template tag where you import CSS/JS files.

First, import the template tag.

{% load compress %}

Compress CSS

{% compress css %}
  <link rel="stylesheet" href="{% static 'css/tailwind.css' %}">
  <link rel="stylesheet" href="{% static 'lib/font-awesome/css/all.min.css' %}">

  {% block extra_css %}
	  {# Override this in templates to add extra stylesheets #}
  {% endblock %}
{% endcompress %}

Compress JS

{% compress js %}
  <script src="{% static 'lib/vue/dist/vue.min.js' %}"></script>
  <script src="{% static 'lib/flowbite/dist/flowbite.min.js' %}"></script>

  {% block extra_js %}
	  {# Override this in templates to add extra javascript #}
  {% endblock %}
{% endcompress %}

Reference Materials

• https://django-compressor.readthedocs.io/en/stable/
• https://flowbite.com/docs/getting-started/django/