django-tailwind-cli 4.8.0__tar.gz → 4.8.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/.github/workflows/test.yml +5 -5
  2. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/CHANGELOG.md +12 -0
  3. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/CONTRIBUTING.md +17 -18
  4. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/PKG-INFO +33 -128
  5. django_tailwind_cli-4.8.1/README.md +135 -0
  6. django_tailwind_cli-4.8.1/docs/installation.md +131 -0
  7. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/docs/settings.md +9 -5
  8. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/docs/template_tags.md +5 -0
  9. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/docs/usage.md +2 -2
  10. django_tailwind_cli-4.8.1/docs/workflow.md +180 -0
  11. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/config.py +51 -236
  12. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/management/commands/_build.py +1 -29
  13. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/management/commands/_download.py +0 -3
  14. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/management/commands/_guides.py +8 -35
  15. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/management/commands/_process.py +0 -2
  16. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/management/commands/tailwind.py +11 -63
  17. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/templatetags/tailwind_cli.py +4 -4
  18. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/utils/http.py +33 -29
  19. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/test_config.py +2 -2
  20. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/test_error_scenarios.py +19 -92
  21. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/test_http.py +97 -1
  22. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/test_integration.py +62 -67
  23. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/test_management_commands.py +0 -4
  24. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/test_tailwind_css_tag.py +106 -0
  25. django_tailwind_cli-4.8.0/README.md +0 -230
  26. django_tailwind_cli-4.8.0/docs/installation.md +0 -136
  27. django_tailwind_cli-4.8.0/docs/workflow.md +0 -160
  28. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/.github/dependabot.yml +0 -0
  29. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/.github/workflows/release.yml +0 -0
  30. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/.gitignore +0 -0
  31. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/.mise/tasks/dev +0 -0
  32. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/.pre-commit-config.yaml +0 -0
  33. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/.readthedocs.yml +0 -0
  34. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/CODE_OF_CONDUCT.md +0 -0
  35. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/LICENSE +0 -0
  36. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/docs/base_template.md +0 -0
  37. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/docs/changelog.md +0 -0
  38. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/docs/conf.py +0 -0
  39. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/docs/contributing.md +0 -0
  40. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/docs/index.md +0 -0
  41. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/docs/requirements.txt +0 -0
  42. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/docs/whitenoise.md +0 -0
  43. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/mise.toml +0 -0
  44. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/pyproject.toml +0 -0
  45. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/__init__.py +0 -0
  46. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/apps.py +0 -0
  47. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/checks.py +0 -0
  48. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/management/__init__.py +0 -0
  49. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/management/commands/__init__.py +0 -0
  50. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/management/commands/_errors.py +0 -0
  51. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/management/commands/_group.py +0 -0
  52. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/management/commands/_source_css.py +0 -0
  53. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/py.typed +0 -0
  54. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/templates/tailwind_cli/base.html +0 -0
  55. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/templates/tailwind_cli/tailwind_css.html +0 -0
  56. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/templatetags/__init__.py +0 -0
  57. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/src/django_tailwind_cli/utils/__init__.py +0 -0
  58. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/.gitignore +0 -0
  59. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/__init__.py +0 -0
  60. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/assets/css/.gitkeep +0 -0
  61. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/assets/css/tailwind.css +0 -0
  62. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/conftest.py +0 -0
  63. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/helpers.py +0 -0
  64. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/settings.py +0 -0
  65. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/templates/tests/base.html +0 -0
  66. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/templates/tests/dummy.email +0 -0
  67. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/test_additional_commands.py +0 -0
  68. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tests/test_checks.py +0 -0
  69. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/tox.ini +0 -0
  70. {django_tailwind_cli-4.8.0 → django_tailwind_cli-4.8.1}/uv.lock +0 -0
@@ -32,7 +32,7 @@ jobs:
32
32
  persist-credentials: false
33
33
 
34
34
  - name: Set up mise
35
- uses: jdx/mise-action@3c2e0cf82a5b2e5249f0d3635a4d83d0ae861518 # v4.2.5
35
+ uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0
36
36
  with:
37
37
  install: true
38
38
  cache: true
@@ -91,7 +91,7 @@ jobs:
91
91
  persist-credentials: false
92
92
 
93
93
  - name: Set up mise
94
- uses: jdx/mise-action@3c2e0cf82a5b2e5249f0d3635a4d83d0ae861518 # v4.2.5
94
+ uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0
95
95
  with:
96
96
  install: true
97
97
  cache: true
@@ -126,7 +126,7 @@ jobs:
126
126
  persist-credentials: false
127
127
 
128
128
  - name: Set up mise
129
- uses: jdx/mise-action@3c2e0cf82a5b2e5249f0d3635a4d83d0ae861518 # v4.2.5
129
+ uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0
130
130
  with:
131
131
  install: true
132
132
  cache: true
@@ -162,7 +162,7 @@ jobs:
162
162
  persist-credentials: false
163
163
 
164
164
  - name: Set up mise
165
- uses: jdx/mise-action@3c2e0cf82a5b2e5249f0d3635a4d83d0ae861518 # v4.2.5
165
+ uses: jdx/mise-action@c2a87611a18de5b3828c5652fe268e992400cb5c # v4.3.0
166
166
  with:
167
167
  install: true
168
168
  cache: true
@@ -190,4 +190,4 @@ jobs:
190
190
  with:
191
191
  persist-credentials: false
192
192
 
193
- - uses: zizmorcore/zizmor-action@3dc1ecc9bcb9e94e9b2c709687979e1298497054 # v0.6.2
193
+ - uses: zizmorcore/zizmor-action@70fb788f84895a7701f5643d103d587e460b5c99 # v0.6.3
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 4.8.1 (2026-09-18)
4
+
5
+ ### 🐛 Bug Fixes
6
+ - **`tailwind build` always rebuilds every stylesheet.** Template changes, imported CSS and build options could previously leave stale output because only the source CSS timestamp was checked. `--force` remains accepted for compatibility but is no longer needed. The build step in `tailwind setup` also always runs.
7
+ - **`{% tailwind_css %}` resolves only stylesheet paths.** Rendering no longer looks up Tailwind releases or searches for a CLI binary, so serving prebuilt CSS does not require a Tailwind installation. CSS configuration errors are still reported; CLI settings are validated by management commands.
8
+ - **Failed CLI downloads leave an existing binary intact.** Downloads are staged on the destination filesystem and replace the binary only after a successful transfer. A mismatch with the advertised `Content-Length` now fails instead of installing an incomplete file; responses without that header remain supported.
9
+
10
+ ### 📚 Documentation
11
+ - Clarified contribution expectations around focused submissions, actionable reports, contributor responsibility and variable review times.
12
+ - Reorganized the README into a working quickstart, the installation guide into setup and optional integrations, and the workflow guide into recurring tasks and troubleshooting.
13
+ - **Source detection guidance corrected:** Tailwind scans automatically by default; `@source` adds paths. Documentation and command guides now explain when to add external sources and how `source(none)` limits scanning to explicit sources.
14
+
3
15
  ## 4.8.0 (2026-08-30)
4
16
 
5
17
  ### 💥 Dependencies
@@ -6,23 +6,22 @@ follows the
6
6
 
7
7
  ## Before you open an issue or a pull request
8
8
 
9
- This project is maintained in spare time. Some weeks are quiet, some weeks the queue is longer than
10
- the time available for it. A few expectations keep that workable:
11
-
12
- - **One topic per issue, one change per pull request.** Small and focused gets handled quickly.
13
- A submission that bundles four unrelated things waits until there is time for all four.
14
- - **Write it so it can be understood on the first read.** What you did, what you expected, what
15
- happened instead. An unclear report gets closed rather than investigated — reconstructing the
16
- missing half costs more time than the fix does.
17
- - **AI-assisted work is fine, unreviewed AI output is not.** You are the author of what you submit.
18
- If you cannot explain every line of it, it is not ready.
19
- - **A quick answer is not an invitation.** A first issue fixed within the hour was well written,
20
- not proof of spare capacity waiting for the next five.
21
- - **The subject line does most of the work.** Say what is broken, not that something is.
22
-
23
- If you are unsure whether something warrants an issue, ask first: open a
9
+ This project is maintained in spare time. Response and review times depend on the available
10
+ capacity and the scope of the work; a quick response to one submission does not set a timeline
11
+ for others.
12
+
13
+ - **Keep submissions focused.** Use one topic per issue and one change per pull request. Submit
14
+ unrelated changes separately so each can be reviewed on its own.
15
+ - **Make reports actionable.** Describe what you did, what you expected, and what happened instead.
16
+ Include reproduction steps and relevant diagnostics so the problem can be investigated.
17
+ - **Review and understand your contribution.** You are responsible for what you submit, including
18
+ work produced with assistance. Check it before submitting and be prepared to explain each change.
19
+ - **Use a specific subject line.** Name the affected command or feature and describe the problem
20
+ or proposed change.
21
+
22
+ For questions about scope or direction, open a
24
23
  [discussion](https://github.com/django-commons/django-tailwind-cli/discussions) or mail
25
- <oliver@andrich.me>. Questions about direction are welcome and cheaper than a rejected pull request.
24
+ <oliver@andrich.me> before starting substantial work.
26
25
 
27
26
  ## Reporting a bug
28
27
 
@@ -98,7 +97,7 @@ Use the scope that names the area you touched. `config`, `management`, `build`,
98
97
  `runserver`, `download`, `http`, `docs`, `tests`, `ci`, and `deps` are the common ones; `git log`
99
98
  shows the rest.
100
99
 
101
- Keep the message short — a title plus one or two sentences on the *why*. The diff already shows
100
+ Keep the message short — a title plus one or two sentences on the _why_. The diff already shows
102
101
  what changed, and test counts or coverage numbers belong in the pull request, not in the history.
103
102
 
104
103
  Commit under your own name and without bot co-author trailers. Whatever tools you used, the change
@@ -118,7 +117,7 @@ Tailwind 4.x, and the major only moves when Tailwind's does. A change that would
118
117
  elsewhere under semver — a dropped dependency, a different exit code — goes into a minor here and
119
118
  is called out in the changelog instead.
120
119
 
121
- Releasing is a tag. `[tool.hatch.version]` reads the version from git, so `v4.8.0` *is* the
120
+ Releasing is a tag. `[tool.hatch.version]` reads the version from git, so `v4.8.0` _is_ the
122
121
  version. Pushing the tag starts the release rather than finishing it: the workflow builds, uploads
123
122
  to TestPyPI, and then waits — the `pypi` environment requires a reviewer, so PyPI publishing needs
124
123
  an admin to approve it in the GitHub UI. Do not push a tag and walk away.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: django-tailwind-cli
3
- Version: 4.8.0
3
+ Version: 4.8.1
4
4
  Summary: Django and Tailwind integration based on the prebuilt Tailwind CSS CLI.
5
5
  Project-URL: Home, https://django-tailwind-cli.rtfd.io/
6
6
  Project-URL: Documentation, https://django-tailwind-cli.rtfd.io/
@@ -58,30 +58,20 @@ follows the approach of the [Tailwind integration for Phoenix](https://github.co
58
58
 
59
59
  - Downloads and manages the Tailwind CLI binary for your platform
60
60
  - Rebuilds CSS on change, running under Django's own auto-reloader
61
- - Produces minified production builds containing only the classes you use, and skips work when
62
- nothing changed
61
+ - Produces minified production builds containing only the classes you use
63
62
  - Includes the CSS via a `{% tailwind_css %}` template tag
64
63
  - Supports [DaisyUI](https://daisyui.com) through [tailwindcss-cli-extra](https://github.com/dobicinaitis/tailwind-cli-extra)
65
64
  - Targets Tailwind CSS 4.x
66
65
 
67
- ## Installation
66
+ ## Quickstart
68
67
 
69
- ### 1. Install the package
68
+ In an existing Django project, install the package:
70
69
 
71
70
  ```bash
72
- # Using pip
73
- pip install django-tailwind-cli
74
-
75
- # Using uv
76
- uv add django-tailwind-cli
77
-
78
- # Using poetry
79
- poetry add django-tailwind-cli
71
+ python -m pip install django-tailwind-cli
80
72
  ```
81
73
 
82
- ### 2. Configure Django settings
83
-
84
- Add to your `settings.py`:
74
+ Add the app and a static files directory to `settings.py`:
85
75
 
86
76
  ```python
87
77
  INSTALLED_APPS = [
@@ -89,22 +79,20 @@ INSTALLED_APPS = [
89
79
  "django_tailwind_cli",
90
80
  ]
91
81
 
92
- # Configure static files directory — make sure it exists on disk,
93
- # Django raises an error at startup if it does not.
94
82
  STATICFILES_DIRS = [BASE_DIR / "assets"]
95
83
  ```
96
84
 
85
+ Create that directory before starting Django:
86
+
97
87
  ```bash
98
88
  mkdir -p assets
99
89
  ```
100
90
 
101
- ### 3. Set up your base template
102
-
103
- Create or update your base template (e.g. `templates/base.html`):
91
+ Load the template tag in your base template and place it inside `<head>`:
104
92
 
105
- ```html
106
- <!DOCTYPE html>
93
+ ```htmldjango
107
94
  {% load tailwind_cli %}
95
+ <!DOCTYPE html>
108
96
  <html lang="en">
109
97
  <head>
110
98
  <meta charset="UTF-8">
@@ -112,58 +100,32 @@ Create or update your base template (e.g. `templates/base.html`):
112
100
  <title>My Django App</title>
113
101
  {% tailwind_css %}
114
102
  </head>
115
- <body class="bg-gray-50">
116
- <div class="container mx-auto px-4">
117
- {% block content %}{% endblock %}
118
- </div>
103
+ <body>
104
+ {% block content %}{% endblock %}
119
105
  </body>
120
106
  </html>
121
107
  ```
122
108
 
123
- ### 4. Start developing
109
+ Start Django and the Tailwind watcher together:
124
110
 
125
111
  ```bash
126
- # Start Django's dev server with a parallel Tailwind watcher
127
112
  python manage.py tailwind runserver
128
-
129
- # Or run build and watch separately
130
- python manage.py tailwind watch # In one terminal
131
- python manage.py runserver # In another terminal
132
113
  ```
133
114
 
134
- The watcher runs under Django's own auto-reloader, so editing `settings.py` (e.g. adding a new app)
135
- restarts it automatically and picks up the new configuration on the fly. Pass `--noreload` to opt
136
- out.
137
-
138
- First run creates a managed `<BASE_DIR>/.django_tailwind_cli/` directory for the CLI binary and an
139
- auto-generated `source.css`. The directory is automatically git-ignored — no entry in your
140
- project-level `.gitignore` needed.
141
-
142
- `python manage.py tailwind setup` walks the same ground: it checks each piece in order, stops at
143
- the first one that is missing with instructions, and performs the download and first build when
144
- they are needed.
115
+ The first run downloads the CLI and creates the default source CSS. Add Tailwind classes to your
116
+ templates; the watcher rebuilds the stylesheet when you save them.
145
117
 
146
- ## Management commands
118
+ For a production build, run Tailwind before collecting static files:
147
119
 
148
- | Command | Purpose | Example |
149
- | -------------- | ---------------------------------------------------- | ---------------------------------------- |
150
- | `setup` | Guided first-time setup and checks | `python manage.py tailwind setup` |
151
- | `build` | Production CSS build | `python manage.py tailwind build` |
152
- | `watch` | Development file watcher (Django autoreload by default) | `python manage.py tailwind watch` |
153
- | `runserver` | Django dev server + watcher (forwards any runserver flag) | `python manage.py tailwind runserver` |
154
- | `config` | Show current configuration | `python manage.py tailwind config` |
155
- | `troubleshoot` | Debug common issues | `python manage.py tailwind troubleshoot` |
156
- | `optimize` | Performance tips for build and watch | `python manage.py tailwind optimize` |
157
- | `download_cli` | Fetch the CLI binary without building | `python manage.py tailwind download_cli` |
158
- | `remove_cli` | Delete the downloaded CLI binary | `python manage.py tailwind remove_cli` |
159
-
160
- `build` takes `--force` to rebuild regardless of change detection; `build` and `watch` both take
161
- `--verbose` for detailed diagnostics.
120
+ ```bash
121
+ python manage.py tailwind build
122
+ python manage.py collectstatic --noinput
123
+ ```
162
124
 
163
- `tailwind runserver` is a transparent passthrough: every positional argument and option (apart from
164
- `--force-default-runserver`) is forwarded verbatim to the underlying `runserver` or
165
- `runserver_plus`. Every flag those commands accept works — including `runserver_plus`-only ones like
166
- `--extra-file`, `--reloader-interval`, and `--print-sql`.
125
+ See the [installation guide](https://django-tailwind-cli.readthedocs.io/latest/installation.html)
126
+ for setup checks and optional integrations, and the
127
+ [workflow guide](https://django-tailwind-cli.readthedocs.io/latest/workflow.html)
128
+ for custom CSS, editor setup and troubleshooting.
167
129
 
168
130
  ## Requirements
169
131
 
@@ -171,78 +133,21 @@ they are needed.
171
133
  - **Django:** 4.2 LTS, 5.2, 6.0, or 6.1
172
134
  - **Platform:** Windows, macOS, Linux (automatic platform detection)
173
135
 
174
- ## Configuration
136
+ ## Configuration and commands
175
137
 
176
- Beyond adding the app to `INSTALLED_APPS`, `STATICFILES_DIRS` is the only setting you have to
177
- configure. Everything below is optional; see the
178
- [settings reference](https://django-tailwind-cli.readthedocs.io/latest/settings.html) for the full
179
- list.
180
-
181
- ```python
182
- # Pin a specific Tailwind version instead of tracking the latest release
183
- TAILWIND_CLI_VERSION = "4.1.3"
138
+ The defaults work with the setup above. Optional settings let you pin the Tailwind version,
139
+ use a system binary, add custom CSS, enable DaisyUI, or include editable-installed external apps.
140
+ See the [settings reference](https://django-tailwind-cli.readthedocs.io/latest/settings.html).
184
141
 
185
- # Custom CSS paths
186
- TAILWIND_CLI_SRC_CSS = "src/styles/main.css"
187
- TAILWIND_CLI_DIST_CSS = "css/app.css"
188
-
189
- # Enable DaisyUI
190
- TAILWIND_CLI_USE_DAISY_UI = True
191
-
192
- # Use an already-installed Tailwind binary (e.g. `brew install tailwindcss`)
193
- TAILWIND_CLI_USE_SYSTEM_BINARY = True
194
-
195
- # Auto-inject @source directives for editable-installed external apps (opt-in)
196
- TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS = True
197
- ```
198
-
199
- For production, pin the version and provide the binary yourself rather than downloading it during a
200
- build:
201
-
202
- ```python
203
- TAILWIND_CLI_VERSION = "4.1.3"
204
- TAILWIND_CLI_AUTOMATIC_DOWNLOAD = False
205
- TAILWIND_CLI_PATH = "/usr/local/bin/tailwindcss" # where your binary actually is
206
- TAILWIND_CLI_DIST_CSS = "css/tailwind.min.css"
207
- ```
208
-
209
- ## DaisyUI
210
-
211
- Setting `TAILWIND_CLI_USE_DAISY_UI = True` switches to the DaisyUI-enabled CLI build, which makes
212
- its component classes available:
213
-
214
- ```html
215
- <button class="btn btn-primary">Primary Button</button>
216
- <div class="card bg-base-100 shadow-xl">
217
- <div class="card-body">
218
- <h2 class="card-title">Card Title</h2>
219
- <p>Card content goes here.</p>
220
- </div>
221
- </div>
222
- ```
223
-
224
- ## Troubleshooting
225
-
226
- **CSS not updating?**
227
-
228
- ```bash
229
- python manage.py tailwind build --force
230
- python manage.py tailwind troubleshoot
231
- ```
232
-
233
- **Configuration problems?**
142
+ The [command reference](https://django-tailwind-cli.readthedocs.io/latest/usage.html) covers all
143
+ commands and options. To inspect your setup or investigate a build problem, start with:
234
144
 
235
145
  ```bash
236
146
  python manage.py tailwind config
237
- python manage.py tailwind setup
147
+ python manage.py tailwind build --verbose
148
+ python manage.py tailwind troubleshoot
238
149
  ```
239
150
 
240
- **Classes from some templates are missing?**
241
-
242
- Make sure every template directory is covered by an `@source` directive in your Tailwind CSS input
243
- file — Tailwind CSS 4.x discovers templates exclusively through those directives. Declaring them
244
- explicitly also keeps builds fast, because Tailwind only scans what you list.
245
-
246
151
  ## Documentation and related projects
247
152
 
248
153
  - [Full documentation](https://django-tailwind-cli.rtfd.io/)
@@ -0,0 +1,135 @@
1
+ # django-tailwind-cli
2
+
3
+ <p style="display: flex; gap: 4px; flex-wrap: wrap; align-items: flex-start; line-height: 1;">
4
+ <img style="height: auto;" alt="GitHub Workflow Status" src="https://img.shields.io/github/actions/workflow/status/django-commons/django-tailwind-cli/test.yml">
5
+ <a style="display: inline-block;" href="https://pypi.org/project/django-tailwind-cli/"><img style="height: auto;" alt="PyPI" src="https://img.shields.io/pypi/v/django-tailwind-cli.svg"></a>
6
+ <a style="display: inline-block;" href="https://github.com/astral-sh/ruff"><img style="height: auto;" alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"></a>
7
+ <a style="display: inline-block;" href="https://github.com/astral-sh/uv"><img style="height: auto;" alt="uv" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json"></a>
8
+ <img style="height: auto;" alt="GitHub" src="https://img.shields.io/github/license/django-commons/django-tailwind-cli">
9
+ <img style="height: auto;" alt="Django Versions" src="https://img.shields.io/pypi/frameworkversions/django/django-tailwind-cli">
10
+ <img style="height: auto;" alt="Python Versions" src="https://img.shields.io/pypi/pyversions/django-tailwind-cli">
11
+ <a style="display: inline-block;" href="https://pepy.tech/project/django-tailwind-cli"><img style="height: auto;" alt="Downloads" src="https://static.pepy.tech/badge/django-tailwind-cli"></a>
12
+ <a style="display: inline-block;" href="https://pepy.tech/project/django-tailwind-cli"><img style="height: auto;" alt="Downloads / Month" src="https://pepy.tech/badge/django-tailwind-cli/month"></a>
13
+ </p>
14
+
15
+ [Tailwind CSS](https://tailwindcss.com) for Django without Node.js. The library downloads the
16
+ standalone [Tailwind CSS CLI](https://tailwindcss.com/blog/standalone-cli) and wires it into Django
17
+ management commands, so there is no npm, no webpack, and no separate build tool to configure. It
18
+ follows the approach of the [Tailwind integration for Phoenix](https://github.com/phoenixframework/tailwind).
19
+
20
+ ## What it does
21
+
22
+ - Downloads and manages the Tailwind CLI binary for your platform
23
+ - Rebuilds CSS on change, running under Django's own auto-reloader
24
+ - Produces minified production builds containing only the classes you use
25
+ - Includes the CSS via a `{% tailwind_css %}` template tag
26
+ - Supports [DaisyUI](https://daisyui.com) through [tailwindcss-cli-extra](https://github.com/dobicinaitis/tailwind-cli-extra)
27
+ - Targets Tailwind CSS 4.x
28
+
29
+ ## Quickstart
30
+
31
+ In an existing Django project, install the package:
32
+
33
+ ```bash
34
+ python -m pip install django-tailwind-cli
35
+ ```
36
+
37
+ Add the app and a static files directory to `settings.py`:
38
+
39
+ ```python
40
+ INSTALLED_APPS = [
41
+ # ... your other apps
42
+ "django_tailwind_cli",
43
+ ]
44
+
45
+ STATICFILES_DIRS = [BASE_DIR / "assets"]
46
+ ```
47
+
48
+ Create that directory before starting Django:
49
+
50
+ ```bash
51
+ mkdir -p assets
52
+ ```
53
+
54
+ Load the template tag in your base template and place it inside `<head>`:
55
+
56
+ ```htmldjango
57
+ {% load tailwind_cli %}
58
+ <!DOCTYPE html>
59
+ <html lang="en">
60
+ <head>
61
+ <meta charset="UTF-8">
62
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
63
+ <title>My Django App</title>
64
+ {% tailwind_css %}
65
+ </head>
66
+ <body>
67
+ {% block content %}{% endblock %}
68
+ </body>
69
+ </html>
70
+ ```
71
+
72
+ Start Django and the Tailwind watcher together:
73
+
74
+ ```bash
75
+ python manage.py tailwind runserver
76
+ ```
77
+
78
+ The first run downloads the CLI and creates the default source CSS. Add Tailwind classes to your
79
+ templates; the watcher rebuilds the stylesheet when you save them.
80
+
81
+ For a production build, run Tailwind before collecting static files:
82
+
83
+ ```bash
84
+ python manage.py tailwind build
85
+ python manage.py collectstatic --noinput
86
+ ```
87
+
88
+ See the [installation guide](https://django-tailwind-cli.readthedocs.io/latest/installation.html)
89
+ for setup checks and optional integrations, and the
90
+ [workflow guide](https://django-tailwind-cli.readthedocs.io/latest/workflow.html)
91
+ for custom CSS, editor setup and troubleshooting.
92
+
93
+ ## Requirements
94
+
95
+ - **Python:** 3.10+
96
+ - **Django:** 4.2 LTS, 5.2, 6.0, or 6.1
97
+ - **Platform:** Windows, macOS, Linux (automatic platform detection)
98
+
99
+ ## Configuration and commands
100
+
101
+ The defaults work with the setup above. Optional settings let you pin the Tailwind version,
102
+ use a system binary, add custom CSS, enable DaisyUI, or include editable-installed external apps.
103
+ See the [settings reference](https://django-tailwind-cli.readthedocs.io/latest/settings.html).
104
+
105
+ The [command reference](https://django-tailwind-cli.readthedocs.io/latest/usage.html) covers all
106
+ commands and options. To inspect your setup or investigate a build problem, start with:
107
+
108
+ ```bash
109
+ python manage.py tailwind config
110
+ python manage.py tailwind build --verbose
111
+ python manage.py tailwind troubleshoot
112
+ ```
113
+
114
+ ## Documentation and related projects
115
+
116
+ - [Full documentation](https://django-tailwind-cli.rtfd.io/)
117
+ - [Tailwind CSS documentation](https://tailwindcss.com)
118
+ - [DaisyUI components](https://daisyui.com)
119
+ - [tailwindcss-cli-extra](https://github.com/dobicinaitis/tailwind-cli-extra) — the DaisyUI-enabled CLI build
120
+ - [Django Extensions](https://django-extensions.readthedocs.io/) — provides `runserver_plus`
121
+ - [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) — VS Code extension
122
+ - [Django Commons](https://github.com/django-commons)
123
+
124
+ ## Contributing
125
+
126
+ Contributions are welcome.
127
+ [CONTRIBUTING.md](https://github.com/django-commons/django-tailwind-cli/blob/main/CONTRIBUTING.md)
128
+ covers the development setup ([mise](https://mise.jdx.dev/) provisions Python, `uv`, and
129
+ `pre-commit`), how to run the tests, and what a pull request should look like. Please read the short
130
+ section at the top of it before opening an issue or a pull request — it explains what makes one easy
131
+ to act on.
132
+
133
+ ## License
134
+
135
+ This software is licensed under [MIT license](https://github.com/django-commons/django-tailwind-cli/blob/main/LICENSE).
@@ -0,0 +1,131 @@
1
+ # Installation
2
+
3
+ For a minimal working setup, see the [quickstart](index.md#quickstart). This page covers the
4
+ setup details and optional integrations for an existing Django project. Supported Python,
5
+ Django and operating system versions are listed in [Requirements](index.md#requirements).
6
+
7
+ ## Install the package
8
+
9
+ Use your project's package manager:
10
+
11
+ ```shell
12
+ python -m pip install django-tailwind-cli
13
+ # Or:
14
+ uv add django-tailwind-cli
15
+ # Or:
16
+ poetry add django-tailwind-cli
17
+ ```
18
+
19
+ ## Configure Django
20
+
21
+ Add `django_tailwind_cli` to `INSTALLED_APPS` in `settings.py`:
22
+
23
+ ```python
24
+ INSTALLED_APPS = [
25
+ # other Django apps
26
+ "django_tailwind_cli",
27
+ ]
28
+ ```
29
+
30
+ Configure `STATICFILES_DIRS` if you have not already done so. The compiled stylesheet is written
31
+ relative to its first entry; the default output is `css/tailwind.css`.
32
+
33
+ ```python
34
+ STATICFILES_DIRS = [BASE_DIR / "assets"]
35
+ ```
36
+
37
+ Create the directory on disk before running Django commands:
38
+
39
+ ```shell
40
+ mkdir -p assets
41
+ ```
42
+
43
+ Load `tailwind_cli` in your base template and add `{% tailwind_css %}` inside `<head>`:
44
+
45
+ ```htmldjango
46
+ {% load tailwind_cli %}
47
+ <head>
48
+ {% tailwind_css %}
49
+ </head>
50
+ ```
51
+
52
+ The tag uses Django's static file storage to resolve the compiled stylesheet. See the
53
+ [template tag reference](template_tags.md) for options, or use the provided
54
+ [base template](base_template.md).
55
+
56
+ ## Check the setup
57
+
58
+ ```shell
59
+ python manage.py tailwind setup
60
+ ```
61
+
62
+ The command checks the configuration and stops at the first blocker with instructions. Once the
63
+ configuration is ready, it downloads the CLI if needed and builds the CSS. It can be run again
64
+ after fixing a reported problem; see [setup](usage.md#setup) for the full sequence.
65
+
66
+ The first build creates `<BASE_DIR>/.django_tailwind_cli/` for the downloaded binary and generated
67
+ `source.css`. A `.gitignore` inside that directory keeps both out of Git. The compiled stylesheet
68
+ is outside that directory: add `assets/css/tailwind.css` to your project's `.gitignore` if you use
69
+ the defaults.
70
+
71
+ The default source CSS is regenerated on builds. For hand-written styles, configure a separate
72
+ file using [`TAILWIND_CLI_SRC_CSS`](settings.md#tailwind_cli_src_css); keep it outside your static
73
+ files directories. See [Editing templates and CSS](workflow.md#editing-templates-and-css).
74
+
75
+ Continue with [Running the development server](workflow.md#running-the-development-server).
76
+
77
+ ## Optional integrations
78
+
79
+ ### Django Extensions
80
+
81
+ Install the extra to use `runserver_plus` and its Werkzeug debugger:
82
+
83
+ ```shell
84
+ python -m pip install "django-tailwind-cli[django-extensions]"
85
+ ```
86
+
87
+ Add `django_extensions` to `INSTALLED_APPS`. `tailwind runserver` then selects `runserver_plus`
88
+ automatically. Pass `--force-default-runserver` when you want Django's standard server instead;
89
+ see [runserver](usage.md#runserver) for forwarded options.
90
+
91
+ ### A system-installed Tailwind CSS CLI
92
+
93
+ If you already have `tailwindcss` on your `PATH`, enable:
94
+
95
+ ```python
96
+ TAILWIND_CLI_USE_SYSTEM_BINARY = True
97
+ ```
98
+
99
+ This skips the managed download. See
100
+ [`TAILWIND_CLI_USE_SYSTEM_BINARY`](settings.md#tailwind_cli_use_system_binary) for binary selection
101
+ and error handling, and the [production configuration](settings.md#production-environment)
102
+ for a pinned, explicitly provisioned binary.
103
+
104
+ ### DaisyUI
105
+
106
+ To use the DaisyUI-enabled CLI build, set:
107
+
108
+ ```python
109
+ TAILWIND_CLI_USE_DAISY_UI = True
110
+ ```
111
+
112
+ See the [DaisyUI settings](settings.md#tailwind_cli_use_daisy_ui) for how the CLI and generated
113
+ source CSS change, and the [DaisyUI configuration examples](settings.md#daisyui) for custom CSS.
114
+ You can then use component classes in templates:
115
+
116
+ ```html
117
+ <button class="btn btn-primary">Primary Button</button>
118
+ <div class="card bg-base-100 shadow-xl">
119
+ <div class="card-body">
120
+ <h2 class="card-title">Card Title</h2>
121
+ <p>Card content goes here.</p>
122
+ </div>
123
+ </div>
124
+ ```
125
+
126
+ ### Browser reload
127
+
128
+ The Tailwind watcher rebuilds CSS on disk. To also reload browser pages automatically, install
129
+ and configure [django-browser-reload](https://github.com/adamchainz/django-browser-reload#installation).
130
+ Its installation guide covers the app, URL route and middleware, including middleware ordering
131
+ and manual script insertion. No additional `django-tailwind-cli` setting is required.
@@ -52,7 +52,7 @@ Enable or disable the automatic downloading of the official CLI to your machine.
52
52
 
53
53
  When enabled, the auto-generated default source CSS file gains one `@source` directive per installed Django app whose path lives **outside** `BASE_DIR` **and** outside every known site-packages directory. This covers exactly one real-world case: editable-installed packages that ship with their own templates, e.g. `pip install -e ../my-ui-library`.
54
54
 
55
- Why it matters: Tailwind CSS 4.x discovers source files by walking the current working directory tree. Apps installed as editable packages from a sibling repository sit outside that tree and are therefore invisible to Tailwind unless declared explicitly. Turning this setting on makes `django-tailwind-cli` emit the declarations for you, using absolute paths that Tailwind can follow.
55
+ Why it matters: the default `@import "tailwindcss";` enables automatic source detection. This package runs the CLI from `BASE_DIR`, which is where that scan starts. Apps installed as editable packages from a sibling repository sit outside that tree and are therefore invisible to Tailwind unless declared explicitly. Turning this setting on makes `django-tailwind-cli` emit the declarations for you, using absolute paths that Tailwind can follow.
56
56
 
57
57
  ```python
58
58
  # settings.py
@@ -69,7 +69,8 @@ With the setting enabled and an editable package `extra` installed, the auto-gen
69
69
  ```
70
70
 
71
71
  :::{note}
72
- The directive points at the app base dir, not at a glob. Tailwind CSS 4.x walks the directory and applies its own exclusions (`.gitignore`, binaries, etc.) — this also means class names embedded in Python files (e.g. form widget `attrs={"class": "..."}` strings) are picked up automatically.
72
+ The directive points at the app base dir, not just its templates. This also covers class names
73
+ embedded in Python files, such as form widget `attrs={"class": "..."}` strings.
73
74
  :::
74
75
 
75
76
  :::{warning}
@@ -311,11 +312,14 @@ TAILWIND_CLI_CSS_MAP = [
311
312
  ]
312
313
  ```
313
314
 
314
- Example source files:
315
+ Example source files using `source(none)` to disable automatic detection and scan only the
316
+ listed templates. Plain `@source` directives supplement automatic detection; they do not
317
+ restrict it. Add any shared template or Python directories that also contain class names. See
318
+ [Tailwind's source detection guide](https://tailwindcss.com/docs/detecting-classes-in-source-files#disabling-automatic-detection).
315
319
 
316
320
  `styles/admin.css`:
317
321
  ```css
318
- @import "tailwindcss";
322
+ @import "tailwindcss" source(none);
319
323
 
320
324
  @source "../templates/admin/**/*.html";
321
325
 
@@ -328,7 +332,7 @@ Example source files:
328
332
 
329
333
  `styles/web.css`:
330
334
  ```css
331
- @import "tailwindcss";
335
+ @import "tailwindcss" source(none);
332
336
 
333
337
  @source "../templates/web/**/*.html";
334
338