tailwindcss:watch exits immediately after build in Docker environment (v4.4.0)

[dapi]

Environment

• tailwindcss-rails: 4.4.0
• tailwindcss-ruby: 4.1.16
• Ruby: 3.4.2
• Rails: 8.1.1
• Docker: Debian-based container
• Watchman: v2024.11.04.00 (installed and working)
• Process manager: Foreman via Procfile.dev

Problem

bin/rails tailwindcss:watch exits immediately after initial build with exit code 0, instead of staying in watch mode.

Procfile.dev

web: bin/rails server
css: bin/rails tailwindcss:watch

Output

14:37:19 css.1  | ≈ tailwindcss v4.1.16
14:37:20 css.1  | Done in 314ms
14:37:20 css.1  | exited with code 0
14:37:20 system | sending SIGTERM to all processes

The CSS process exits immediately after "Done", which triggers foreman to send SIGTERM to all other processes.

Investigation

1. Watchman is installed and working

$ watchman version
version: 20251222.073500.0
buildinfo: v2024.11.04.00

$ watchman watch-list
{
    "version": "20251222.073500.0",
    "roots": [
        "/app"
    ]
}

2. Bug in watch_command method

In lib/tasks/build.rake:

def watch_command(always: false, **kwargs)
  compile_command(**kwargs).tap do |command|
    command << "-w"
    command << "always" if always  # This produces: -w always (two separate args)
  end
end

This generates -w always as two separate arguments, but the tailwindcss CLI expects --watch=always or --watch always as a single flag with value.

3. Even with correct flag, tailwindcss exits

Tried running directly:

$ bundle exec tailwindcss --input app/assets/stylesheets/application.css --output app/assets/builds/application.css --watch=always
≈ tailwindcss v4.1.16

Done in 455ms
$ # Process exits immediately

Expected Behavior

The tailwindcss:watch task should stay running and rebuild CSS when source files change.

Workaround Attempted

• Passing always argument: css: bin/rails tailwindcss:watch[always] - doesn't work
• Direct tailwindcss command with --watch=always - exits immediately
• FIFO stdin wrapper to keep stdin open - exits immediately

Possible Causes

1. The watch_command method incorrectly constructs the watch flag
2. Tailwindcss v4 may have different stdin/tty requirements for watch mode
3. In Docker/non-interactive environment, tailwindcss may need additional flags

Suggested Fix

At minimum, fix the watch_command to properly pass the flag:

def watch_command(always: false, **kwargs)
  compile_command(**kwargs).tap do |command|
    command << (always ? "--watch=always" : "--watch")
  end
end

But there may be a deeper issue with tailwindcss v4 watch mode in non-interactive environments.

[dapi]

Working workaround

After testing various approaches, here's what works for Tailwind CSS v4 in Docker:

Custom watch script with checksum-based polling

#!/usr/bin/env bash
# bin/tailwind-watch
# Workaround for tailwindcss v4 watch mode not working

INPUT="app/assets/stylesheets/application.css"
OUTPUT="app/assets/builds/application.css"
CHECKSUM_FILE="/tmp/tailwind-checksum"

# Calculate checksum of relevant files
calculate_checksum() {
  find app/assets/stylesheets app/views app/helpers app/javascript app/components \
    -type f \( -name "*.css" -o -name "*.html" -o -name "*.erb" -o -name "*.slim" -o -name "*.rb" -o -name "*.js" \) \
    -exec md5sum {} \; 2>/dev/null | sort | md5sum | cut -d' ' -f1
}

# Initial build
echo "[tailwind-watch] Initial build..."
bundle exec tailwindcss -i "$INPUT" -o "$OUTPUT"
calculate_checksum > "$CHECKSUM_FILE"

echo "[tailwind-watch] Watching for changes (polling every 1s)..."

# Poll for changes
while true; do
  sleep 1
  NEW_CHECKSUM=$(calculate_checksum)
  OLD_CHECKSUM=$(cat "$CHECKSUM_FILE" 2>/dev/null || echo "")

  if [ "$NEW_CHECKSUM" != "$OLD_CHECKSUM" ]; then
    echo "[tailwind-watch] Changes detected, rebuilding..."
    bundle exec tailwindcss -i "$INPUT" -o "$OUTPUT"
    echo "$NEW_CHECKSUM" > "$CHECKSUM_FILE"
  fi
done

Then in Procfile.dev or Procfile.docker:

css: bin/tailwind-watch

What doesn't work

Tested the following - none of them work with tailwindcss v4.1.16:

• bin/rails tailwindcss:watch - exits immediately
• bin/rails tailwindcss:watch -- --poll - exits immediately (no --poll in v4)
• --watch=always flag - ignored, exits immediately
• Keeping stdin open with /dev/zero - doesn't help
• Watchman installed and working - doesn't help

The native tailwindcss v4 binary seems to have a fundamental issue with watch mode in non-interactive environments.