DOCSEARCHbyAlgolia
Submit Docs

django-tailwind-cli

repository·main·Indexed 42 days ago

https://github.com/django-commons/django-tailwind-cli

Django and Tailwind CSS integration based on the prebuilt Tailwind CSS CLI. It allows using Tailwind CSS in Django projects without requiring Node.js or npm by managing the CLI binary directly and integrating the build process into Django management commands.

Tokens
14.2K
Snippets
58
Records
74
Agent score
51%

What's inside django-tailwind-cli

  1. Avoid placing source CSS in static directories

    main

    Do not point TAILWIND_CLI_SRC_CSS or any files in TAILWIND_CLI_CSS_MAP to locations inside your STATICFILES_DIRS.

    WhiteNoise (via Django's ManifestStaticFilesStorage) rewrites @import statements in CSS files. Because Tailwind source files often use @import "tailwindcss";, WhiteNoise will attempt to find a file named tailwindcss in your static directories and fail with a whitenoise.storage.MissingFileError.

    Keep your source CSS in a directory outside of your static paths (the default .django_tailwind_cli/ is safe).

  2. Quickstart: Install and set up django-tailwind-cli

    main

    To use Tailwind CSS in an existing Django project without Node.js, follow these steps:

    1. Install the package via pip:

      python -m pip install django-tailwind-cli

    2. Configure settings.py: Add django_tailwind_cli to your INSTALLED_APPS and define a STATICFILES_DIRS path (e.g., assets).

      INSTALLED_APPS = [
    # ... your other apps
    "django_tailwind_cli",
]

STATICFILES_DIRS = [BASE_DIR / "assets"]

    3. Prepare the assets directory: Create the directory defined in STATICFILES_DIRS before starting the server.

      mkdir -p assets

    4. Add the template tag: Load tailwind_cli in your base template and place the {% tailwind_css %} tag inside the <head> section.

    5. Run the development server: Use the integrated command to start Django and the Tailwind watcher simultaneously.

      python manage.py tailwind runserver

      Note: The first run will automatically download the Tailwind CLI binary and create the default source CSS.

    python -m pip install django-tailwind-cli

  3. Build CSS before running collectstatic

    main

    When deploying with WhiteNoise, you must run the Tailwind build command before running collectstatic. If collectstatic is run first, the manifest will not contain an entry for the generated stylesheet, causing a ValueError when the site attempts to render {% tailwind_css %}.

    Correct build order:

    1. Build the CSS using python manage.py tailwind build.
    2. Collect static files using python manage.py collectstatic --noinput.
    python manage.py tailwind build
python manage.py collectstatic --noinput

  4. Configure Tailwind CLI for Docker Compose

    main

    When running Tailwind in watch mode (via tailwind runserver or tailwind watch) inside a Docker container, the Tailwind CLI requires a TTY-enabled environment to function correctly.

    You must set tty: true in your docker-compose.yml for the service running the Tailwind commands.

    web:
  command: python manage.py tailwind runserver
  tty: true

# or

tailwind-sidecar:
  command: python manage.py tailwind watch
  tty: true

  5. Build Tailwind CSS for production

    main

    For production environments, you must generate a minified CSS build containing only the classes used in your project. This should be performed before running collectstatic.

    Run the following commands in order:

    1. Build the CSS:

      python manage.py tailwind build

    2. Collect static files:

      python manage.py collectstatic --noinput
    python manage.py tailwind build
python manage.py collectstatic --noinput

  6. Configure environments (Staging vs Production)

    main

    Tailwind configuration should vary based on your deployment environment to balance developer flexibility with production stability and performance.

    Staging: Allows automatic downloads and uses a pinned stable version. Production: Disables automatic downloads, uses a pre-installed binary at a specific path, and uses minified/optimized output.

    # settings/staging.py
TAILWIND_CLI_VERSION = "4.1.3"  # Pin to stable version
TAILWIND_CLI_AUTOMATIC_DOWNLOAD = True  # Allow downloads
TAILWIND_CLI_DIST_CSS = "css/tailwind.min.css"  # Minified output

# settings/production.py
TAILWIND_CLI_VERSION = "4.1.3"  # Pin exact version
TAILWIND_CLI_AUTOMATIC_DOWNLOAD = False  # Disable downloads
TAILWIND_CLI_PATH = "/usr/local/bin/tailwindcss"  # Pre-installed CLI
TAILWIND_CLI_DIST_CSS = "css/tailwind.min.css"  # Optimized output

  7. Development workflow with WhiteNoise

    main

    During development, whitenoise.runserver_nostatic allows WhiteNoise to serve static files. By default, WHITENOISE_AUTOREFRESH and WHITENOISE_USE_FINDERS follow your settings.DEBUG value.

    When DEBUG = True, stylesheets rebuilt by tailwind runserver or tailwind watch are automatically picked up on the next request without needing to restart the Django server. If you find your browser is serving stale files, ensure WHITENOISE_AUTOREFRESH is not explicitly set to False.

  8. Configure django-tailwind-cli with WhiteNoise

    main

    To use django-tailwind-cli with WhiteNoise, you can use the default settings. Ensure whitenoise.runserver_nostatic is placed before django.contrib.staticfiles in INSTALLED_APPS, and whitenoise.middleware.WhiteNoiseMiddleware is placed directly after django.middleware.security.SecurityMiddleware in MIDDLEWARE.

    By default, the source CSS is kept in <BASE_DIR>/.django_tailwind_cli/source.css (outside static directories) and the build output is placed in <STATICFILES_DIRS[0]>/css/tailwind.css. This structure is compatible with WhiteNoise's manifest storage.

    # settings.py

INSTALLED_APPS = [
    # ...
    "whitenoise.runserver_nostatic",  # before django.contrib.staticfiles
    "django.contrib.staticfiles",
    "django_tailwind_cli",
]

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "whitenoise.middleware.WhiteNoiseMiddleware",  # directly after SecurityMiddleware
    # ...
]

STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "static"  # collectstatic target, not a source directory
STATICFILES_DIRS = [BASE_DIR / "assets"]  # where the CLI writes css/tailwind.css

STORAGES = {
    "staticfiles": {
        "BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage",
    },
}

  9. Use the django-tailwind-cli base template

    main

    The package provides a minimal base template (tailwind_cli/base.html) designed to serve as a starting point for projects using Tailwind CSS. This template automatically includes the necessary CSS stylesheets and the {% tailwind_css %} template tag.

    To use it, extend the template in your own Django template files using the {% extends %} tag.

    {% extends "tailwind_cli/base.html" %}

  10. Configure default django-tailwind-cli setup

    main

    For a standard installation, you only need to add django_tailwind_cli to your INSTALLED_APPS and ensure STATICFILES_DIRS is configured to point to your assets directory.

    # settings.py
INSTALLED_APPS = [
    # ...
    "django_tailwind_cli",
]

STATICFILES_DIRS = [BASE_DIR / "assets"]

  11. Configure django-tailwind-cli in Django settings

    main

    To integrate the package into your Django project, follow these steps:

    1. Add to INSTALLED_APPS: Add django_tailwind_cli to your settings.py.
    2. Configure STATICFILES_DIRS: Ensure STATICFILES_DIRS is configured. The compiled stylesheet is written relative to the first entry in this list. By default, it outputs to css/tailwind.css.
    3. Create the directory: Manually create the directory specified in STATICFILES_DIRS before running commands.

    Example configuration:

    INSTALLED_APPS = [
    # other Django apps
    "django_tailwind_cli",
]

# The compiled stylesheet will be written to assets/css/tailwind.css
STATICFILES_DIRS = [BASE_DIR / "assets"]
    INSTALLED_APPS = [
    "django_tailwind_cli",
]

STATICFILES_DIRS = [BASE_DIR / "assets"]