[v4] cli --watch seems to watch unneeded directories

[doits]

What version of Tailwind CSS are you using?

v4.0.0

What build tool (or framework if it abstracts the build tool) are you using?

@twailwindcss/cli

What version of Node.js are you using?

v20.18.1

What browser are you using?

N/A

What operating system are you using?

Ubuntu 20.04

Reproduction URL

N/A

Describe your issue

I have the following directory structure:

scss/tailwind.css

another.php
index.php

files/models/A_LOT_OF_DIRECTORIES # <-- 1000+ dirs

My scss/tailwind.css looks like this:

@layer theme, base, components, utilities;

@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/utilities.css" layer(utilities) source(none);

@source "../*.php";

Reason: I only want tailwindcss to scan the php files in the root directory, nothing more, especially nothing in subdirectories.

Compiling works:

npx @tailwindcss/cli -i scss/tailwind.css -o c/tailwind.css -m
≈ tailwindcss v4.0.0

Done in 165ms

But when I add --watch:

npx @tailwindcss/cli -i scss/tailwind.css -o c/tailwind.css -m --watch
≈ tailwindcss v4.0.0

Done in 9s

Notice how long it takes.

And sometimes I get this error:

node:internal/process/promises:391
    triggerUncaughtException(err, true /* fromPromise */);
    ^

[Error: inotify_add_watch on '/path/to/project/root/files/models/offerpdf/755411' failed: No space left on device]

What is it doing in files/models/offerpdf? It looks like it wants to watch this directory, but why? It isn't added to @source at all.

When I only source a subdirectory (@source "../some_dir/*.php";) the problem goes away.

Is there something broken with setting up the watchers since v4? I had no problems with v3 with the same configuration (through a tailwind.config.js though, but same/similar pattern only watching *.php in the root dir.).

[doits]

Still present with 4.0.3.

Here is the output with DEBUG:

$ DEBUG=1 npx @tailwindcss/cli -i scss/tailwind.css -o c/tailwind.css -m --watch
≈ tailwindcss v4.0.3

Done in 9s

[9972.22ms] [@tailwindcss/cli] (initial build)
[  46.95ms]   ↳ Setup compiler
[  17.05ms]   ↳ Scan for candidates
[  43.13ms]   ↳ Build CSS
[   3.73ms]   ↳ Optimize CSS
[   0.73ms]   ↳ Write output

Without watch:

$ DEBUG=1 npx @tailwindcss/cli -i scss/tailwind.css -o c/tailwind.css -m
≈ tailwindcss v4.0.3

Done in 118ms

[120.28ms] [@tailwindcss/cli] (initial build)
[ 29.14ms]   ↳ Setup compiler
[ 31.18ms]   ↳ Scan for candidates
[ 46.82ms]   ↳ Build CSS
[  3.82ms]   ↳ Optimize CSS
[  0.46ms]   ↳ Write output

[Ramblurr]

You might be interested in
https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources
https://tailwindcss.com/docs/detecting-classes-in-source-files#disabling-automatic-detection

[czak]

I've also observed this behavior.

My test case

Project:

.
├── css
│   └── in.css
├── index.html
└── Makefile

Contents of css/in.css:

@import "tailwindcss" source(none);

@source "../index.html";

Command:

tailwindcss -i css/in.css -o css/out.css -w

I would expect tailwindcss to only react to changes in index.html.
But it also reacts to changes in Makefile

Hypothesis

I think the watcher discards filename and watches all of ../.
I believe @source deals with directories and my expectation to only scan index.html is not correct.

[doits]

I believe @source deals with directories and my expectation to only scan index.html is not correct.

Good idea! That makes sense and would explain the behaviour.

[philipp-spiess]

@doits Hey! Sorry for the late reply here. Unfortunately that's an implementation detail that we can't really fix. We use @parcel/watcher under the hood for @tailwindcss/cli and that only allows you to subscribe to whole directories so we have to do the file extension based matching afterwards: https://github.com/parcel-bundler/watcher?tab=readme-ov-file#watching.

I'm not sure why it takes 9 seconds to set up the single watcher for you, though. Do you have watchman installed by any chance? If yes you could try uninstalling it or vice versa.

[doits]

Thanks for the reply!

I just run it with DEBUG='*' and it takes 22 seconds between these steps:

2025-05-14T15:18:32.871710Z  INFO get_normalized_sources: tailwindcss_oxide::scanner: exit
2025-05-14T15:18:55.259433Z  INFO scan_sources: tailwindcss_oxide::scanner: enter

Maybe this helps to see where it takes so much time?

watchman is not installed. Installed it via apt and now it took even longer (29 seconds), though that might be regular variance.

I have a lot of directories inside my project, parts of node_modules are symlinked at multiple places, too. Is it possible that there are simply too many folders to watch? I tried to ignore some with @source not but then #17985 got in my way, so I cannot ignore them (though I don't know if @source not will make the watcher faster / ignore folders).

[philipp-spiess]

@doits Thanks! Will investigate further. What version of @tailwindcss/cli are you running?

[doits]

v4.1.6

[doits]

Just want to not that it is still present with v4.1.11

I got this error message:

$ DEBUG='*' yarn run tailwindcss -i scss/tailwind.css -o c/tailwind.css -m -w
≈ tailwindcss v4.1.11

[DEBUG] Writing debug info to: `/path/to/project/root/tailwindcss-49383.log`


[29573.42ms] [@tailwindcss/cli] (initial build)
[   32.17ms]   ↳ Setup compiler

node:internal/process/promises:394
    triggerUncaughtException(err, true /* fromPromise */);
    ^

[Error: A non-recoverable condition has triggered.  Watchman needs your help!
The triggering condition was at timestamp=1753356110: inotify-add-watch(/path/to/project/root/files/models/offerpdf/822034) -> The user limit on the total number of inotify watches was reached; increase the fs.inotify.max_user_watches sysctl
All requests will continue to fail with this message until you resolve
the underlying problem.  You will find more information on fixing this at
https://facebook.github.io/watchman/docs/troubleshooting.html#poison-inotify-add-watch
]

#17985 still blocks me from ignoring the directory unfortunately.