Tailwind v4 parsing warnings when scanning Rails gem source files on Heroku

[trevorturk]

Tailwind v4 parsing warnings when scanning Rails gem source files on Heroku

Summary

Tailwind CSS v4 generates parsing warnings when it scans Ruby on Rails gem source files that contain RDoc cross-reference syntax during Heroku deployments. This occurs because Heroku installs gems inside the project directory (vendor/bundle), which Tailwind then scans, encountering patterns like {method}[rdoc-ref:Target#method!] that contain ! characters invalid as CSS tokens.

Environment

• Tailwind CSS: v4 (via tailwindcss-rails 4.4.0)
• Ruby on Rails: 8.1.1
• Platform: Heroku (Ruby buildpack)
• Deployment: Heroku uses bundle install --path vendor/bundle --deployment

Reproduction

Why it happens on Heroku but not locally:

1. Heroku: Installs gems to ./vendor/bundle/ruby/3.4.0/gems/ (inside project)
2. Local: Installs gems to system location like ~/.rbenv/versions/3.4.7/lib/ruby/gems/ (outside project)
3. Tailwind v4: With @import "tailwindcss"; and no explicit @source directives, recursively scans the current working directory
4. On Heroku: Tailwind finds and scans vendor/bundle, including Rails framework source files
5. Locally: Tailwind never sees gem files because they're outside the project directory

Specific warnings:

Unexpected token Delim("!") at 1:14 in {*_will_change!}[rdoc-ref: #* will_change!]
  Location: vendor/bundle/ruby/3.4.0/gems/activemodel-8.1.1/lib/active_model/dirty.rb:111

Unexpected token Delim("!") at 1:14 in {destroy!}[rdoc-ref:Persistence#destroy!]
  Location: vendor/bundle/ruby/3.4.0/gems/activerecord-8.1.1/lib/active_record/errors.rb:169

Unexpected token Delim("!") at 1:14 in {save!}[rdoc-ref:Persistence#save!]
  Location: vendor/bundle/ruby/3.4.0/gems/activerecord-8.1.1/lib/active_record/errors.rb:147 (+ 5 other files)

Unexpected token Delim("!") at 1:14 in {update_attribute!}[rdoc-ref:Persistence#update_attribute!]
  Location: vendor/bundle/ruby/3.4.0/gems/activerecord-8.1.1/lib/active_record/errors.rb:148

Example source code triggering warnings:

# From activerecord-8.1.1/lib/active_record/errors.rb:147
# Rails uses RDoc cross-reference syntax in inline documentation:
# {ActiveRecord::Base#save!}[rdoc-ref:Persistence#save!]

The ! character is valid in Ruby method names but invalid as a CSS token.

Impact

• ✅ Deployment succeeds
• ✅ CSS builds correctly
• ✅ Application functions normally
• ⚠️ Build logs show 4 cosmetic warnings
• ⚠️ No way to suppress warnings without modifying Rails framework source

Research Completed

We conducted comprehensive research and found:

• ❌ No existing GitHub issues documenting this interaction
• ❌ No Tailwind v4 CLI flags to suppress specific warnings
• ❌ No way to exclude subdirectories in vendor/ (Tailwind v4 removed v3 exclusion syntax)
• ❌ .gemrc doesn't work (Bundler ignores it)
• ❌ @source directives can't prevent scanning individual gem directories

Possible Solutions

1. Add warning suppression options (Feature Request)

Add CLI flags or configuration to suppress warnings by:

• File path patterns (e.g., --suppress-warnings="vendor/**")
• Specific warning types (e.g., --suppress="Unexpected token Delim")

2. Improve RDoc handling

Tailwind could recognize common documentation patterns like:

• {text}[rdoc-ref:Target] (RDoc cross-references)
• {text}[rdoc-label:Label] (RDoc labels)
• And skip parsing them as CSS

3. Better @source exclusion syntax

Restore or enhance the ability to exclude paths from scanning:

@import "tailwindcss";
@source "app/**" exclude "vendor/**";

4. Documentation

Document this edge case and recommended workarounds for Rails developers deploying to Heroku.

Current Workaround

Accept the warnings as cosmetic. They indicate Tailwind correctly identified patterns it cannot parse, but don't affect functionality.

Related Context

• RDoc syntax: Standard Ruby documentation format used throughout Rails framework
• Heroku deployment: Common platform for Rails applications
• Rails 8.1.1: Current stable release of Ruby on Rails
• Tailwind v4: Latest major version with new CSS-first architecture

This appears to be an undocumented edge case - a novel interaction between Rails framework documentation conventions, Heroku's gem installation strategy, and Tailwind v4's content scanning behavior.

Questions

1. Is there already a way to exclude specific directories from scanning that we missed?
2. Would you accept a PR adding warning suppression options?
3. Should this be documented as a known limitation?

Thank you for considering this issue. Happy to provide additional details or test proposed solutions.

[jaybloke]

Experienced the same problem and used this in my css file:

@import "tailwindcss"; 
@source not "/usr/src/app/vendor/**";
...

More info on exclusions here: https://tailwindcss.com/docs/detecting-classes-in-source-files#ignoring-specific-paths