Plain
Documentation
Docs plain-tailwind plain tailwind README.md

plain.tailwind

Integrate Tailwind CSS without JavaScript or npm.

Overview

You can use Tailwind CSS in your Plain project without Node.js or npm. This package automatically downloads and manages the Tailwind standalone CLI for you.

Initialize Tailwind in your project:

plain tailwind init

This creates a tailwind.css source file in your project root. Then compile your CSS:

plain tailwind build

For development, use watch mode to automatically recompile when files change:

plain tailwind build --watch

Include the compiled CSS in your templates:

<!DOCTYPE html>
<html>
<head>
    {% tailwind_css %}
</head>
<body>
    <h1 class="text-3xl font-bold text-blue-600">Hello, Tailwind!</h1>
</body>
</html>

CLI commands

plain tailwind init

Sets up Tailwind in your project. This command:

  1. Downloads the Tailwind standalone CLI (if not already installed)
  2. Creates a tailwind.css source file in your project root
plain tailwind init

plain tailwind build

Compiles your Tailwind CSS from the source file to app/assets/tailwind.min.css.

# One-time build
plain tailwind build

# Watch mode for development
plain tailwind build --watch

# Minified build for production
plain tailwind build --minify

The build command automatically installs or updates the Tailwind CLI if needed.

plain tailwind update

Updates to the latest version of Tailwind CSS:

plain tailwind update

This downloads the newest version and updates your pyproject.toml.

Template tag

The tailwind_css template tag includes the compiled CSS file in your templates. Place it in your base template's <head>:

<!DOCTYPE html>
<html>
<head>
    {% tailwind_css %}
</head>
<body>
    {% block content %}{% endblock %}
</body>
</html>

The tag renders a <link> element pointing to your compiled CSS file.

Configuration

Custom source and output paths

You can customize where the source and compiled CSS files are located by setting these in your app/settings.py:

# app/settings.py
from pathlib import Path

# Source CSS file (default: project_root/tailwind.css)
TAILWIND_SRC_PATH = Path("/path/to/your/tailwind.css")

# Compiled CSS output (default: app/assets/tailwind.min.css)
TAILWIND_DIST_PATH = Path("/path/to/output/tailwind.min.css")

The Tailwind version is tracked in your pyproject.toml:

[tool.plain.tailwind]
version = "4.0.0"

When you run plain tailwind build, it automatically checks if your local installation matches this version and updates if needed.

Adding custom CSS

Add custom CSS to your source file (by default tailwind.css at the project root):

@import "tailwindcss";
@import "./.plain/tailwind.css";

/* Add your custom styles here */
.btn-primary {
    @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded;
}

.custom-gradient {
    background: linear-gradient(to right, #4f46e5, #7c3aed);
}

The @import "./.plain/tailwind.css" line includes styles from all your installed Plain packages.

Read the Tailwind docs for more about using custom styles.

Deployment

For production deployments:

  1. Add app/assets/tailwind.min.css to your .gitignore
  2. Run plain tailwind build --minify as part of your deployment process

The build command automatically installs the Tailwind CLI if it is not present, making deployments seamless.

You can automate this by adding a build command to your pyproject.toml:

[tool.plain.build.run]
tailwind = {cmd = "plain tailwind build --minify"}

FAQs

How does this work without Node.js?

Tailwind provides a standalone CLI that bundles everything needed to compile CSS. This package downloads the appropriate binary for your platform (macOS, Linux, or Windows) and manages it for you.

Where is the Tailwind CLI stored?

The Tailwind binary and version information are stored in a .plain directory in your project root. Add this to your .gitignore:

.plain/

How do I use Tailwind classes from other Plain packages?

The @import "./.plain/tailwind.css" line in your source CSS automatically includes @source directives for all installed Plain packages. This ensures Tailwind scans those packages for class usage.

Can I use Tailwind plugins?

The standalone CLI includes all first-party plugins. For third-party plugins that require npm, you would need to use the standard Tailwind installation instead.

Installation

Install the plain.tailwind package from PyPI:

uv add plain.tailwind

Add plain.tailwind to your INSTALLED_PACKAGES:

# app/settings.py
INSTALLED_PACKAGES = [
    # ...
    "plain.tailwind",
]

Add .plain/ to your .gitignore:

.plain/

Initialize Tailwind in your project:

plain tailwind init

Add the tailwind_css template tag to your base template:

<!DOCTYPE html>
<html>
<head>
    {% tailwind_css %}
</head>
<body>
    {% block content %}{% endblock %}
</body>
</html>

Run the build command to compile your CSS:

plain tailwind build --watch