From fd2505954c9a077ae17cee3e55dadd0434272776 Mon Sep 17 00:00:00 2001 From: Mike Dalessio Date: Sat, 5 Apr 2025 09:39:13 -0400 Subject: [PATCH] Improve the state of debugging when things go wrong - The "verbose" flag turns on additional debugging output from tailwindcss - Document the "watchman" problem - Document how to use the "verbose" flag when troubleshooting --- README.md | 35 ++++++++++++++++++++++++++++++++++- lib/tailwindcss/commands.rb | 6 ++++++ lib/tasks/build.rake | 16 ++++++++++++---- 3 files changed, 52 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c9982de6..7188adff 100644 --- a/README.md +++ b/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. diff --git a/lib/tailwindcss/commands.rb b/lib/tailwindcss/commands.rb index bef42fd2..99ad30e0 100644 --- a/lib/tailwindcss/commands.rb +++ b/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 diff --git a/lib/tasks/build.rake b/lib/tasks/build.rake index 3044ff05..603c8059 100644 --- a/lib/tasks/build.rake +++ b/lib/tasks/build.rake @@ -2,9 +2,13 @@ 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" @@ -12,9 +16,13 @@ namespace :tailwindcss do 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