Adds Standalone CLI support: Use Django-Tailwind CSS without Node.js

Author: timonweb

.pre-commit-config.yaml

@@ -50,4 +50,4 @@ repos:
     - id: ruff-check
       args: [ --fix ]
     - id: ruff-format
-exclude: 'src/tailwind/app_template_v3/{{cookiecutter.app_name}}/apps.py|src/tailwind/app_template_v4/{{cookiecutter.app_name}}/apps.py|src/tailwind/app_template_v4/{{cookiecutter.app_name}}/static_src/package.json'
+exclude: 'src/tailwind/app_template_v3/{{cookiecutter.app_name}}/apps.py|src/tailwind/app_template_v4/{{cookiecutter.app_name}}/apps.py|src/tailwind/app_template_v4/{{cookiecutter.app_name}}/static_src/package.json|src/tailwind/app_template_v4_standalone/{{cookiecutter.app_name}}/apps.py'

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 4.4.0 (Unreleased)
+
+- Standalone Tailwind CSS binary support via [pytailwindcss](https://github.com/timonweb/pytailwindcss);
+- `TAILWIND_USE_STANDALONE_BINARY` setting to force standalone binary mode;
+- `TAILWIND_STANDALONE_BINARY_VERSION` setting to control standalone binary version (default: `v4.1.16`);
+- Automatic detection of standalone vs npm-based installations (checks for `package.json` presence);
+- `app_template_v4_standalone/` cookiecutter template for standalone binary apps;
+- Updates documentation;
+- Node.js is now optional when using standalone binary mode;
+
 ## 4.3.0
 
 - Replaces Poetry with UV for dependency management;

CLAUDE.md

@@ -6,6 +6,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Django-Tailwind is a Python package that integrates Tailwind CSS with Django applications. It provides management commands, template tags, and utilities to streamline Tailwind CSS development within Django projects.
 
+The package supports two installation modes:
+- **npm-based:** Traditional approach using Node.js and npm for maximum flexibility (plugins, PostCSS, etc.)
+- **Standalone binary:** Simplified approach using the Tailwind CSS standalone binary via pytailwindcss (no Node.js required)
+
 ## Development Commands
 
 ### Testing
@@ -76,9 +80,11 @@ python manage.py tailwind build
 
 - **Management Command** (`src/tailwind/management/commands/tailwind.py`):
   - Main entry point for all Tailwind operations
-  - Handles `init`, `install`, `build`, `start`, `dev`, `check-updates`, `update` commands
+  - Handles `init`, `install`, `build`, `start`, `dev`, `check-updates`, `update`, `plugin_install` commands
   - Uses cookiecutter templates for app initialization
   - `dev` command runs Django server and Tailwind watcher simultaneously using Honcho
+  - Automatically detects and routes between npm-based and standalone binary modes
+  - Standalone detection checks for `package.json` presence or `TAILWIND_USE_STANDALONE_BINARY` setting
 
 - **NPM Integration** (`src/tailwind/npm.py`):
   - Wrapper around npm commands
@@ -96,23 +102,55 @@ python manage.py tailwind build
 
 ### App Templates
 
-Two cookiecutter templates are provided:
-- `app_template_v3/` - For Tailwind CSS v3
-- `app_template_v4/` - For Tailwind CSS v4
+Three cookiecutter templates are provided:
+- `app_template_v3/` - For Tailwind CSS v3 (npm-based)
+- `app_template_v4/` - For Tailwind CSS v4 (npm-based)
+- `app_template_v4_standalone/` - For Tailwind CSS v4 standalone binary
 
-These templates generate Django apps with:
+**npm-based templates** (`v3` and `v4`) generate Django apps with:
 - `static_src/` directory for source files
 - `package.json` with build scripts
 - PostCSS configuration
 - Base HTML template
 
+**Standalone template** (`v4_standalone`) generates minimal Django apps with:
+- `static_src/src/` directory with styles.css
+- No `package.json` or npm dependencies
+- No PostCSS configuration
+- Base HTML template
+- Pre-created `static/` directory structure
+
 ### Configuration
 
 The package uses Django settings for configuration:
 - `TAILWIND_APP_NAME` - Name of the Tailwind app
 - `TAILWIND_CSS_PATH` - Path to compiled CSS
-- `TAILWIND_DEV_MODE` - Development mode flag
-- `NPM_BIN_PATH` - Custom npm binary path
+- `TAILWIND_DEV_MODE` - Development mode flag (deprecated)
+- `NPM_BIN_PATH` - Custom npm binary path (npm-based only)
+- `TAILWIND_USE_STANDALONE_BINARY` - Force standalone binary mode (default: False, auto-detected)
+- `TAILWIND_STANDALONE_BINARY_VERSION` - Tailwind CSS standalone binary version (default: "v4.1.16")
+
+### Standalone Binary Implementation
+
+The standalone binary mode uses [pytailwindcss](https://github.com/timonweb/pytailwindcss) to run the Tailwind CSS standalone binary without requiring Node.js.
+
+**How it works:**
+1. Detection happens in the management command via `self.is_standalone` flag
+2. Checks for `TAILWIND_USE_STANDALONE_BINARY` setting OR absence of `package.json`
+3. Routes command execution to either npm methods or standalone methods
+
+**Commands behavior:**
+- `init --tailwind-version 4s`: Creates standalone app using `app_template_v4_standalone`
+- `install`: Downloads standalone binary via pytailwindcss (auto-install on first use)
+- `build`: Runs `pytailwindcss.run()` with minify flag
+- `start`: Runs `pytailwindcss.run()` with watch flag
+- `dev`: Works with standalone mode (Procfile uses `tailwind start`)
+- `check-updates`, `update`, `plugin_install`: Raise CommandError (not supported in standalone)
+
+**Key implementation methods in `tailwind.py`:**
+- `tailwind_cli_install_command()`: Downloads binary via pytailwindcss
+- `tailwind_cli_build_command()`: Builds CSS with standalone binary
+- `tailwind_cli_start_command()`: Starts watcher with standalone binary
 
 ## Common Development Patterns
 

README.md

@@ -13,13 +13,14 @@
 
 This project provides a convenient way to integrate the *Tailwind CSS* framework into a Django project.
 It creates a new Django app (named theme by default) that includes all the necessary files and configurations to get
-started with *Tailwind CSS* quickly.
+started with *Tailwind CSS* quickly and **without even needing to install `Node.js`** if you choose the standalone binary mode.
 
 ## Features
 
 * An opinionated *Tailwind CSS* setup that makes your life easier;
+* **Two installation modes:** standalone binary (works without `Node.js`) or npm-based (`Node.js` required);
 * Hot reloading of CSS, configuration files, and *Django* templates. No more manual page refreshes!
-* Out of the box support for CSS imports, Sass-like variables, and nesting;
+* Out of the box support for CSS imports and nesting;
 * Supports the latest *Tailwind CSS* `v4.x`;
 * Start both *Tailwind CSS* and *Django* development servers with a single command;
 * An optional DaisyUI integration to spice up your Tailwind templates with pre-built components.
@@ -29,6 +30,8 @@ started with *Tailwind CSS* quickly.
 
 Python 3.11 or newer and Django 4.2.20 or newer.
 
+**Note:** `Node.js` is only required if you choose the npm-based installation. The standalone binary mode does not require Node.js.
+
 ## Documentation
 
 The full documentation is at https://django-tailwind.readthedocs.io/ or in the [docs directory](docs/index.md) of this

docs/index.md

@@ -13,6 +13,7 @@ To avoid confusion, we'll use:
 Contents
 --------
 * [Installation](installation.md)
+* [Standalone vs npm-based](standalone-vs-npm.md)
 * [Usage](usage.md)
 * [Settings](settings.md)
 * [Template tags](templatetags.md)

docs/installation.md

@@ -42,12 +42,9 @@
    python manage.py tailwind init
    ```
 
-   > Note: By default, we create an app compatible with Tailwind CSS version 4. If you want to create an app compatible
-   > with Tailwind CSS version 3, you can use the `--tailwind-version 3` flag:
+   You will need to provide the name of the app and choose the installation method: standalone binary or npm-based.
 
-    ```bash
-    python manage.py tailwind init --tailwind-version 3
-    ```
+   > See [Standalone vs npm-based](./standalone-vs-npm.md) for a detailed comparison.
 
 4. Add your newly created `'theme'` app to `INSTALLED_APPS` in `settings.py`:
 
@@ -158,7 +155,7 @@
 
 ## Optional configurations
 
-### @source directive configuration (for Tailwind CSS v4)
+### @source directive configuration (for npm-based v4 and standalone v4)
 
 The `content` section from Tailwind CSS v3 has been replaced with the `@source` directive in Tailwind CSS v4.
 The `@source` directive is a new way to specify the source files that Tailwind CSS should scan for class names. It's
@@ -177,7 +174,7 @@ three directories above the `style.css` file. Depending on your project structur
 For more information about setting `@source`, check out the *"Source Configuration"* page of the Tailwind CSS docs:
 [https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources](https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources).
 
-### Content (formerly Purge) rules configuration (for Tailwind CSS v3)
+### Content (formerly Purge) rules configuration (for npm-based Tailwind CSS v3 only)
 
 The `content` section of your `tailwind.config.js` file is where you configure the paths to all of your HTML templates,
 JavaScript components, and any other source files that contain *Tailwind* class names.
@@ -211,9 +208,11 @@ HTML files (or files containing HTML content, such as `.vue` or `.jsx` files) ar
 For more information about setting `content`, check out the *"Content Configuration"* page of the Tailwind CSS
 docs: [https://tailwindcss.com/docs/content-configuration](https://tailwindcss.com/docs/content-configuration).
 
-### Configuration of the path to the `npm` executable
+### Configuration of the path to the `npm` executable (npm-based installation only)
+
+> **Note:** This section only applies to npm-based installations. Skip if using the standalone binary mode.
 
-*Tailwind CSS* requires *Node.js* to be installed on your machine.
+For npm-based installations, *Tailwind CSS* requires *Node.js* to be installed on your machine.
 *Node.js* is a *JavaScript* runtime that allows you to run *JavaScript* code outside the browser. Most (if not all) of
 the current frontend tools depend on *Node.js*.
 

docs/plugins.md

@@ -1,12 +1,16 @@
 # Installing Tailwind CSS Plugins
 
+> **Important:** Plugin installation via the `plugin_install` command is **only available for npm-based installations**. If you're using the standalone binary mode (initialized with `--tailwind-version 4s`), the `plugin_install` command is not supported. Standalone installations are limited to core Tailwind CSS features only.
+
 Django Tailwind provides built-in support for managing Tailwind CSS plugins. This guide covers how to install, configure, and manage plugins in your Tailwind CSS projects.
 
 ## Overview
 
 Tailwind CSS plugins extend the framework's functionality by adding new utilities, components, and base styles. Django Tailwind makes it easy to install and configure these plugins through management commands.
 
-## Installing Plugins
+## Installing Plugins (npm-based Installation Only)
+
+> **Note:** All commands in this section require an npm-based installation. These commands will not work with standalone binary installations.
 
 ### Using the plugin_install Command
 
@@ -106,11 +110,11 @@ python manage.py tailwind plugin_install @tailwindcss/forms
 - Better default appearance for form controls
 - Easy to customize with Tailwind utilities
 
-## Installing Plugins During Project Initialization
+## Installing Plugins During Project Initialization (npm-based Only)
 
 ### DaisyUI Integration
 
-For Tailwind v4 projects, you can include DaisyUI directly during project initialization:
+For npm-based Tailwind v4 projects, you can include DaisyUI directly during project initialization:
 
 ```bash
 python manage.py tailwind init --include-daisy-ui

docs/settings.md

@@ -10,10 +10,10 @@ python manage.py tailwind init
 ```
 Please refer to the [Installation](installation.md) section for more information on the installation process.
 
-## `TAILWIND_DEV_MODE` (deprecated)
-Determines whether the `browser-sync` snippet is added to the page via the `{% tailwind_css %}` tag. It is set to `False` by default. If you use a legacy pre-`3.1.0` configuration and rely on `browser-sync`, add `TAILWIND_DEV_MODE=True` to your `settings.py`.
+## `NPM_BIN_PATH` (npm-based installation only)
+
+> **Note:** This setting only applies to npm-based installations. Skip if using the standalone binary mode.
 
-## `NPM_BIN_PATH`
 This defines the path to the `npm` executable on your system.
 
 > *Tailwind CSS* requires you to have *Node.js* installed on your machine.
@@ -32,6 +32,98 @@ Please note that on *Windows* the path might look different (pay attention to th
 NPM_BIN_PATH = r"C:\Program Files\nodejs\npm.cmd"
 ```
 
+## `TAILWIND_USE_STANDALONE_BINARY`
+
+This setting determines whether to use the Tailwind CSS standalone binary instead of npm-based installation.
+
+The default value is:
+```python
+TAILWIND_USE_STANDALONE_BINARY = False
+```
+
+When set to `True`, Django Tailwind will use the [pytailwindcss](https://github.com/timonweb/pytailwindcss) package to run the Tailwind CSS standalone binary. This eliminates the need for Node.js and npm.
+
+> **Note:** In most cases, you don't need to set this manually. Django Tailwind automatically detects standalone installations by checking for the presence of `package.json` in your theme app. If you initialized your app with `--tailwind-version 4s`, this detection happens automatically.
+
+To explicitly enable standalone mode:
+
+```python
+# settings.py
+TAILWIND_USE_STANDALONE_BINARY = True
+```
+
+## `TAILWIND_STANDALONE_BINARY_VERSION`
+
+This setting specifies which version of the Tailwind CSS standalone binary to use.
+
+The default value is:
+```python
+TAILWIND_STANDALONE_BINARY_VERSION = "v4.1.16"
+```
+
+You can specify any valid Tailwind CSS version tag. To upgrade to a newer version:
+
+```python
+# settings.py
+TAILWIND_STANDALONE_BINARY_VERSION = "v4.2.0"
+```
+
+After changing this setting, run `python manage.py tailwind install` to download the new binary version.
+
+> **Note:** This setting only applies when using standalone binary mode. For npm-based installations, the version is controlled by the `package.json` file in your theme app.
+
+**Finding available versions:**
+
+Visit the [Tailwind CSS releases page](https://github.com/tailwindlabs/tailwindcss/releases) to see all available versions. Use the tag name (e.g., `v4.1.16`) as the value for this setting.
+
+## `TAILWIND_STANDALONE_START_COMMAND_ARGS`
+
+> **Note:** This setting only applies when using standalone binary mode.
+
+This setting defines the command-line arguments passed to the Tailwind CSS standalone binary when running in watch mode (via `python manage.py tailwind start`).
+
+The default value is:
+```python
+TAILWIND_STANDALONE_START_COMMAND_ARGS = (
+    "-i static_src/src/styles.css -o static/css/dist/styles.css --watch"
+)
+```
+
+You can customize this to use different input/output paths or add additional Tailwind CLI options:
+
+```python
+# settings.py
+TAILWIND_STANDALONE_START_COMMAND_ARGS = (
+    "-i theme/static_src/input.css -o theme/static/output.css --watch --minify"
+)
+```
+
+> **Note:** The output path automatically uses the value from `TAILWIND_CSS_PATH` in the default configuration. If you override this setting, ensure your paths are correct.
+
+## `TAILWIND_STANDALONE_BUILD_COMMAND_ARGS`
+
+> **Note:** This setting only applies when using standalone binary mode.
+
+This setting defines the command-line arguments passed to the Tailwind CSS standalone binary when building for production (via `python manage.py tailwind build`).
+
+The default value is:
+```python
+TAILWIND_STANDALONE_BUILD_COMMAND_ARGS = (
+    "-i static_src/src/styles.css -o static/css/dist/styles.css --minify"
+)
+```
+
+You can customize this to use different input/output paths or modify build options:
+
+```python
+# settings.py
+TAILWIND_STANDALONE_BUILD_COMMAND_ARGS = (
+    "-i theme/static_src/input.css -o theme/static/output.css --minify --optimize"
+)
+```
+
+> **Note:** The output path automatically uses the value from `TAILWIND_CSS_PATH` in the default configuration. If you override this setting, ensure your paths match your project structure.
+
 ## `TAILWIND_CSS_PATH`
 This defines the path to the generated *Tailwind CSS* stylesheet. If you created a theme app via the `python manage.py tailwind init` command, you likely don't need to change this value.
 
@@ -41,3 +133,6 @@ The default value is:
 ```python
 TAILWIND_CSS_PATH = "css/dist/styles.css"
 ```
+
+## `TAILWIND_DEV_MODE` (deprecated)
+Determines whether the `browser-sync` snippet is added to the page via the `{% tailwind_css %}` tag. It is set to `False` by default. If you use a legacy pre-`3.1.0` configuration and rely on `browser-sync`, add `TAILWIND_DEV_MODE=True` to your `settings.py`.

docs/standalone-vs-npm.md

@@ -0,0 +1,30 @@
+# Standalone vs npm-based installation
+
+Django Tailwind offers two methods for integrating Tailwind CSS into your Django project: using an npm-based setup or a
+standalone binary. Each method has its own advantages and trade-offs. The table below compares the two approaches to help
+you decide which one is best suited for your needs.
+
+| Feature              | npm-based                 | Standalone Binary     |
+|----------------------|---------------------------|-----------------------|
+| **Node.js Required** | ✅ Yes                     | ❌ No                  |
+| **Setup Complexity** | Moderate                  | Simple                |
+| **Tailwind Version** | v3 or v4                  | v4 only               |
+| **Plugin Support**   | ✅ Full                    | ❌ None                |
+| **DaisyUI Support**  | ✅ Yes                     | ❌ No                  |
+| **Custom PostCSS**   | ✅ Yes                     | ❌ No                  |
+| **Plugin Install**   | `tailwind plugin_install` | ❌ Not available       |
+| **package.json**     | ✅ Created                 | ❌ Not created         |
+| **node_modules**     | ✅ Created                 | ❌ Not created         |
+| **Best For**         | Teams, complex projects   | Solo, simple projects |
+
+**Choose npm-based if you:**
+- Need Tailwind plugins (DaisyUI)
+- Want to customize PostCSS configuration
+- Prefer managing dependencies with package.json
+- Need the plugin management commands
+
+**Choose standalone binary if you:**
+- Want the simplest possible setup
+- Don't have or don't want to install Node.js
+- Don't need plugins or advanced customization
+- Are building a basic project with core Tailwind features