Improve the state of debugging when things go wrong

README.md

@@ -403,30 +403,63 @@ If you need to use a custom input or output file, you can run `bundle exec tailw
 
 ## Troubleshooting
 
-Some common problems experienced by users ...
+When having trouble with `tailwindcss:build` or `tailwindcss:watch`, the first thing you should do is collect some diagnostic information by setting the "verbose" flag, which will emit:
+
+1. the command being run (so you can try running `tailwindcss` yourself without the gem's help)
+2. additional debugging output from `tailwindcss` by setting the env var `DEBUG=1`
+
+Here's what that looks like:
+
+``` sh
+$ bin/rails tailwindcss:build[verbose]
+
+Running: /path/to/tailwindcss-ruby-4.0.17-x86_64-linux-gnu/exe/x86_64-linux-gnu/tailwindcss -i /home/flavorjones/code/oss/tailwindcss-rails/My Workspace/test-install/app/assets/tailwind/application.css -o /home/flavorjones/code/oss/tailwindcss-rails/My Workspace/test-install/app/assets/builds/tailwind.css --minify
+≈ tailwindcss v4.0.17
+
+Done in 37ms
+
+[38.22ms] [@tailwindcss/cli] (initial build)
+[11.90ms]   ↳ Setup compiler
+[ 6.52ms]   ↳ Scan for candidates
+[10.39ms]   ↳ Build CSS
+[ 1.69ms]   ↳ Optimize CSS
+[ 5.80ms]   ↳ Write output
+```
+
+### The `watch` command is hanging
+
+There is a [known issue](https://github.com/tailwindlabs/tailwindcss/issues/17246#issuecomment-2753067488) running `tailwindcss -w` (that's the CLI in watch mode) when the utility `watchman` is also installed.
+
+Please try uninstalling `watchman` and try running the watch task again.
+
 
 ### Lost keystrokes or hanging when using terminal-based debugging tools (e.g. IRB, Pry, `ruby/debug`...etc.) with the Puma plugin
 
 We've addressed the issue and you can avoid the problem by upgrading `tailwindcss-rails` to [v2.4.1](https://github.com/rails/tailwindcss-rails/releases/tag/v2.4.1) or later versions.
 
+
 ### Running in a docker container exits prematurely
 
 If you are running `rails tailwindcss:watch` as a process in a Docker container, set `tty: true` in `docker-compose.yml` for the appropriate container to keep the watch process running.
 
 If you are running `rails tailwindcss:watch` in a docker container without a tty, pass the `always` argument to the task to instruct tailwindcss to keep the watcher alive even when `stdin` is closed: `rails tailwindcss:watch[always]`. If you use `bin/dev` then you should modify your `Procfile.dev`.
 
+
 ### Conflict with sassc-rails
 
 Tailwind uses modern CSS features that are not recognized by the `sassc-rails` extension that was included by default in the Gemfile for Rails 6. In order to avoid any errors like `SassC::SyntaxError`, you must remove that gem from your Gemfile.
 
+
 ### Class names must be spelled out
 
 For Tailwind to work, your class names need to be spelled out. If you need to make sure Tailwind generates class names that don't exist in your content files or that are programmatically composed, use the [safelist option](https://tailwindcss.com/docs/content-configuration#safelisting-classes).
 
+
 ### `ERROR: Cannot find the tailwindcss executable` for supported platform
 
 See https://github.com/flavorjones/tailwindcss-ruby for help.
 
+
 ### Using asset-pipeline assets
 
 In Rails, you want to use [assets from the asset pipeline to get fingerprinting](https://guides.rubyonrails.org/asset_pipeline.html#fingerprinting-versioning-with-digest-based-urls). However, Tailwind isn't aware of those assets.

lib/tailwindcss/commands.rb

@@ -29,6 +29,12 @@ def watch_command(always: false, poll: false, **kwargs)
         end
       end
 
+      def command_env(verbose:)
+        {}.tap do |env|
+          env["DEBUG"] = "1" if verbose
+        end
+      end
+
       def rails_css_compressor?
         defined?(Rails) && Rails&.application&.config&.assets&.css_compressor.present?
       end

lib/tasks/build.rake

@@ -2,19 +2,27 @@ namespace :tailwindcss do
   desc "Build your Tailwind CSS"
   task build: :environment do |_, args|
     debug = args.extras.include?("debug")
+    verbose = args.extras.include?("verbose")
+
     command = Tailwindcss::Commands.compile_command(debug: debug)
-    puts command.inspect if args.extras.include?("verbose")
-    system(*command, exception: true)
+    env = Tailwindcss::Commands.command_env(verbose: verbose)
+    puts "Running: #{Shellwords.join(command)}" if verbose
+
+    system(env, *command, exception: true)
   end
 
   desc "Watch and build your Tailwind CSS on file changes"
   task watch: :environment do |_, args|
     debug = args.extras.include?("debug")
     poll = args.extras.include?("poll")
     always = args.extras.include?("always")
+    verbose = args.extras.include?("verbose")
+
     command = Tailwindcss::Commands.watch_command(always: always, debug: debug, poll: poll)
-    puts command.inspect if args.extras.include?("verbose")
-    system(*command)
+    env = Tailwindcss::Commands.command_env(verbose: verbose)
+    puts "Running: #{Shellwords.join(command)}" if verbose
+
+    system(env, *command)
   rescue Interrupt
     puts "Received interrupt, exiting tailwindcss:watch" if args.extras.include?("verbose")
   end