TailwindCSS v4 - upgrade experience report

[excid3]

First off, everything works great with Tailwind v4 beta. 🎉

One of the changes is that it uses CSS-first configuration now. This is helpful and makes the tailwind.config.js optional. In fact, the config can be specified inside the CSS now, for backwards compatibility.

@import "tailwindcss";
@config "../../config/tailwind.config.js";

v4 Also uses LightningCSS, so autoprefixer, postcss-present-env, etc are also no longer required.

The recommended way for configuring now is using CSS variables for everything and since the config is optional now, I would consider removing it from the installer.

Also probably need to re-evaluate how this is handled in compile_command. It seems like the config option is ignored if the file doesn't exist, so that didn't cause any issues with the upgrade for me.

One other thing that I would mention is their upgrade tool. A few of the class names have changed and TailwindCSS v4 now includes it's own built-in import support. The upgrade tool can take care of a good 90% or more of updating from v3.

npx @tailwindcss/upgrade@next

I'm not sure if it makes sense to do anything other than drop this into the README or an UPGRADE.md doc, but it is very helpful.

[flavorjones]

@excid3 Thanks so much for the experience report. I definitely want to update the documentation with an "upgrade" section so it's very helpful to have access to someone's experience other than my own.

If other folks want to add their notes there, I would be very thankful! 🙏

[Dandush03]

Sure, I think the migration process is kind of trasnparent, just not really explicit

Like, with importmap, it's not posible to migrate the files, we must install the npm package, and stuff like that, but regardless of that, after the migration it stop recompiling classes in rb files

[flavorjones]

Tailwind CSS v4 is out, as is v4.0.0 of the tailwindcss-ruby gem.

The upstream upgrade guide is at https://tailwindcss.com/docs/upgrade-guide.

If you're not ready to upgrade, then pin your project to the 3.x releases:

# If you're not ready to upgrade yet!
gem "tailwindcss-rails", "~> 3.3.1"

[flavorjones]

I've created a parent issue for improving the upgrade experience and making the gem work better with v4: Improve support for Tailwind CSS v4 · Issue #462 · rails/tailwindcss-rails

[flavorjones]

Working on automating upgrade here: #466

[EricGusmao]

For context, my environment does not use any JavaScript tooling—I am only using this gem and nothing else.

The Tailwind upgrade tool fails if the packages required in tailwind.config.js (e.g., plugins) are not installed via npm beforehand. My workaround was to install the missing packages globally and rerun the tool, which resolved the issue. Aside from that, everything has been working great so far!

PS: After running the upgrade tool in another stack project that uses React, I noticed it also migrates the class names in the markup. However, this migration is not being applied to ERB files when run in a Rails project. I'm trying to figure out how to make it work (If there's a way).

[EricGusmao]

@flavorjones
After spending some time tinkering, reading through Tailwind upgrade tool source code and testing with some dummy rails apps, I discovered some new things that are important to mention:

• Class names migrations relies on postcss
• The upgrade tool assumes the postcss config file is at the current directory where the tool is executed, consequently, it completely ignores this gem convention of adding postcss.config.js to config/ dir (and there is no cli option to override).
• And after doing some tweaks, yes, class names migrations do work.

[flavorjones]

I've released a v4.0.0.rc1 release candidate. I would appreciate feedback if anyone has time to try it out, both upgrading existing apps and installing tailwind into apps.

https://github.com/rails/tailwindcss-rails/releases/tag/v4.0.0.rc1

Just drop a note here to let me know if it works, or if it doesn't. Unless something unexpected comes up, I plan to cut a final release tomorrow, 2025-01-24.

[flavorjones]

Ran into a few small issues which are being addressed with:

• remove inter font before upgrading using the npx script #469
• fix: unnecessary stylesheet_link_tag for tailwind #473
• Move application.tailwind.css to a dir ignored by propshaft #474

I'm planning to cut another release candidate to get another round of feedback.

[drale2k]

I just gave it a try but running into issue trying to run the upgrade command. I am not using any JS bundling. Just this gem. Same setup as @EricGusmao above

bin/rails tailwindcss:upgrade

      apply  /Users/drale2k/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/tailwindcss-rails-4.0.0.rc1/lib/install/upgrade_tailwindcss.rb
  Removing references to 'defaultTheme' from /Users/drale2k/work/playground/myproject/data/code/config/tailwind.config.js
        gsub    config/tailwind.config.js
10.9.2
  Running the upstream Tailwind CSS upgrader
         run    npx @tailwindcss/upgrade@next --force --config /Users/drale2k/work/playground/podcast_search/data/code/config/tailwind.config.js from "."
≈ tailwindcss v4.0.0

│ Searching for CSS files in the current directory and its subdirectories… 

│ ↳ Linked `./config/tailwind.config.js` to `./app/assets/stylesheets/application.tailwind.css` 

│ Migrating JavaScript configuration files… 

│ ↳ Could not load the configuration file: Cannot find module '@tailwindcss/forms' 
│   Require stack: 
│   - /Users/drale2k/work/playground/myproject/data/code/config/tailwind.config.js 

  The upgrade tool failed!
          You probably need to update your configuration. Please read the error messages,
          and check the Tailwind CSS upgrade guide at https://tailwindcss.com/docs/upgrade-guide.

It seems to be expecting tailwind being installed using npm, having a node_modules folder present? Is there an upgrade path without that?

[EricGusmao]

Perhaps you should try: npm install -g tailwind@3.4.17 @tailwindcss/forms @tailwindcss/aspect-ratio @tailwindcss/typography @tailwindcss/container-queries

[flavorjones]

Same error as previously

which error? please please please provide the command you ran and what the complete output was.

[drale2k]

Same as in my comment above #450 (comment)

I followed the suggestion below to disable all plugins. Now it ran without errors but doing that, the upgrade does not rename the changed class names.

[EricGusmao]

Renaming classes only work with postcss.

[drale2k]

I had to disable all plugins listen in the tailwind.config.js. If that's as intended then it worked.

[octave]

New install seems to work fine.

[hansondr]

Using an existing Rails 8.1.0.alpha app, Propshaft, and devcontainer without Node I didn't run into any issues manually upgrading following: https://tailwindcss.com/docs/upgrade-guide as indicated.

When starting bin/dev I was initially thrown by the output from the tailwindcss cli process:

css.1  | sh: 1: watchman: not found
css.1  | ≈ tailwindcss v4.0.0
css.1  | 
css.1  | Done in 1s

Thinking I was missing a dependency but turns out it's just a notice and changes are picked up automatically as expected.

[nirvdrum]

It may be worth adding a note that watchman is an optional dependency used by the Tailwind executable. I found myself in a situation where part of the upgrade didn't work, which manifested as the files not being reloaded, so I assumed the watchman message was the cause. I grepped through tailwindcss-ruby and tailwindcss-rails to figure out where the call was coming from. It turns out that the source was the tailwindcss executable, which is native, so grep naturally didn't work.

In the end, my problem was entirely unrelated to watchman, but since the output message looked like an error and things weren't working, I started there. Hopefully it'll get addressed upstream. apt install watchman gets rid of the message, but I'm not sure it really buys me anything over inotify.

[mwala-zm]

Also note that some errors may be caused by plugins in your tailwindcss.config.js while running ./bin/rails tailwindcss:upgrade . I had to comment out require("daisyui") from my config file for the upgrade to work.

[drale2k]

Did you disable all plugins, including first party plugins such as @tailwindcss/forms and @tailwindcss/typography?

[mwala-zm]

Yes I did, running the command displayed The upgrade tool failed! with those plugins still in the file.

[drale2k]

After being able to have the upgrade script run successfully, the watcher using bin/rails tailwindcss:watch has stopped working. I have it as part of my Procfile.dev (worked fine until now). I also tried it as a puma plugin .

In both cases the server stops with the following log output when running bin/dev:

23:30:53 web.1    | => Booting Puma
23:30:53 web.1    | => Rails 8.0.1 application starting in development 
23:30:53 web.1    | => Run `bin/rails server --help` for more startup options
23:30:53 web.1    | Puma starting in single mode...
23:30:53 web.1    | * Puma version: 6.5.0 ("Sky's Version")
23:30:53 web.1    | * Ruby version: ruby 3.4.1 (2024-12-25 revision 48d4efcb85) +YJIT +PRISM [arm64-darwin24]
23:30:53 web.1    | *  Min threads: 3
23:30:53 web.1    | *  Max threads: 3
23:30:53 web.1    | *  Environment: development
23:30:53 web.1    | *          PID: 43869
23:30:53 web.1    | * Listening on http://127.0.0.1:3000
23:30:53 web.1    | * Listening on http://[::1]:3000
23:30:53 web.1    | Use Ctrl-C to stop
23:30:53 css.1    | W, [2025-01-23T23:30:53.163978 #43872]  WARN -- : [meilisearch-ruby] The top-level module of Meilisearch has been renamed.
23:30:53 css.1    | [meilisearch-ruby] Please update "MeiliSearch" to "Meilisearch".
23:30:53 css.1    | 
23:30:53 worker.1 | W, [2025-01-23T23:30:53.169935 #43871]  WARN -- : [meilisearch-ruby] The top-level module of Meilisearch has been renamed.
23:30:53 worker.1 | [meilisearch-ruby] Please update "MeiliSearch" to "Meilisearch".
23:30:53 worker.1 | 
23:30:53 worker.1 | [GoodJob] [43871] GoodJob 4.8.0 started scheduler with queues=fast max_threads=3.
23:30:53 worker.1 | [GoodJob] [43871] GoodJob 4.8.0 started scheduler with queues=default,fast max_threads=5.
23:30:53 worker.1 | [GoodJob] [43871] GoodJob 4.8.0 started scheduler with queues=* max_threads=5.
23:30:53 worker.1 | [GoodJob] GoodJob started cron with 2 jobs.
23:30:53 worker.1 | [GoodJob] Notifier subscribed with LISTEN
23:30:54 css.1    | exited with code 0
23:30:54 system   | sending SIGTERM to all processes
23:30:54 web.1    | - Gracefully stopping, waiting for requests to finish
23:30:54 web.1    | Exiting
23:30:54 web.1    | terminated by SIGTERM
23:30:55 web.1    | exited with code 0

When trying to run it standalone in console, it just returns without any error:

bin/rails tailwindcss:watch
>

with poll

bin/rails tailwindcss:watch[poll]
> zsh: no matches found: tailwindcss:watch[poll]

[flavorjones]

I'll take a look in the morning.

[flavorjones]

@drale2k I can't reproduce this on my dev machine. Please open an issue and we can figure out what's going on. Thanks!

[danielpaul]

I'm getting the same. Was able to narrow it down to the tailwind.config.js file being added to the css file as @config '../../../config/tailwind.config.js';. Removing this line make it work. Hope this helps for debugging. It could be because of certain values in the tailwind.config.js file.

[flavorjones]

@danielpaul Please open an issue if you can describe how to reproduce it. Thank you!

[drale2k]

Thanks @danielpaul that worked. Opened an issue #475

[EricGusmao]

@drale2k @mwala-zm @flavorjones

I think I've found a better way to handle plugin migrations without relying on the npm -g flag or npm install, which somehow defaults to my home directory as the node package directory if there’s no package.json in my working directory (maybe it’s because of mise). Anyway, let’s get started!!

Guide

Warning

To replace the class names accordingly for v4, go to config/tailwind.config.js update the content part to:

  content: [
    '../public/*.html',
    '../app/helpers/**/*.rb',
    '../app/javascript/**/*.js',
    '../app/views/**/*.{erb,haml,html,slim}'
  ],

( Just add an additional . to all the paths referenced )

If you’re not using any JS tooling, do the following:

After updating tailwindcss-rails, add the following line to the .gitignore file:

/node_modules

(So the Tailwind update tool won’t dig through your node_modules files and infer incorrect migrations, because it complies with .gitignore constraints)

Then create a package.json in the root of the project:

{
  "name": "app_name",
  "version": "1.0.0",
  "dependencies": {
    "tailwindcss": "^3.4.17", // Mandatory!!
    // Install all plugins and modules that are referenced in tailwind.config.js
    "@tailwindcss/aspect-ratio": "^0.4.2",
    "@tailwindcss/container-queries": "^0.1.1",
    "@tailwindcss/forms": "^0.5.10",
    "@tailwindcss/typography": "^0.5.16"
    // And so on...
  }
}

Now the upgrade task should run fine.

Delete package.json, node_modules/ and package-lock.json (or yarn.lock), remove /node_modules from .gitignore.

Go to your CSS file and remove the following line (if present):

@plugin '@tailwindcss/container-queries';

If there’s something I’m missing, anyone can feel free to point it out. Improvements on this procedure or better solutions—please share. Thanks!

[flavorjones]

I'd love to start with it in the README, yes please open a PR when you can.

[mrispoli24]

When I delete all the node files Delete package.json, node_modules/ and package-lock.json (or yarn.lock), remove /node_modules from .gitignore my develop command fails. Are we sure we can actually remove these now?

[jeduardo824]

I'm facing a similar issue of @mrispoli24 when running the watch command: Error: Can't resolve '@tailwindcss/container-queries'

This is the start of my application.css:

@import 'tailwindcss';
@config '../../../config/tailwind.config.js';
@plugin '@tailwindcss/container-queries';
@plugin '@tailwindcss/forms';
@plugin '@tailwindcss/typography';

And I removed the plugin's session from the tailwind.config.js file.

Anyone with the same issue?

[EricGusmao]

@jeduardo824 container-queries are already built-in in tailwind v4, you can just remove this line and it will fix it.

[EricGusmao]

@mrispoli24 could you please show us the error message?

[octave]

Also when there is no tailwind.config.js the Intellisense extension doesn't activate. I'm not sure if this is related to the gem or the Intellisense VSCode extension, but I wanted to cross link it here just in case: tailwindlabs/tailwindcss-intellisense#1145 (comment)

[flavorjones]

@octave I think the VScode extension will probably need to be updated to detect tailwind some other way, since v4 encourages developers to drop the config file in favor of putting configuration into the application CSS. Please do comment here if I turn out to be completely wrong! 🙏

[octave]

From @thecrypticace:

You're using the Standalone CLI with Rails and the bundled Tailwind CSS version in IntelliSense is still v3.4. I'll have to come up with a solution to bundle both and pick the right one when its not installed via npm.

[flavorjones]

👋 v4.0.0.rc5 has been released. This is likely what's going to be in the final release, so please try it out if you have a few minutes today or tomorrow. Thank you!

[drale2k]

Looks good, all working. Thanks for your time 🚀

[mwala-zm]

Can we have an update to the readme to add "build:css": "tailwindcss -i ./app/assets/tailwind/application.css -o ./app/assets/builds/application.css --minify" to the package.json to update the css build path for devs using foreman. I'm not sure if the issue persists with precompiling assets.

[mwala-zm]

When I ran the upgrade command the build:css script in the package.json would still point to the stylesheets/application.tailwind.css path and would prevent the server from booting outputting Specified input file ./app/assets/stylesheets/application.tailwind.css does not exist.

[flavorjones]

Sorry, I have no idea what "the build:css script in the package.json" is, it's not something that this gem installed or that this gem's documentation discusses. 🤷 I understand that you have a script or command in your application that does something with the asset file path, but I don't see how that relates to this gem. Help me understand.

[mwala-zm]

When you install tailwindcss on an app using esbuild, it inserts a CSS build script in the package.json which before v4 pointed to the stylesheets/application.tailwind.css after the upgrade, that script is not updated to point to the new updated path. Which may cause a stylesheet not found error on boot

[flavorjones]

@mwala-zm Sorry, I still don't understand what that has to do with this project. I think you're confused. If you installed tailwind using esbuild, you probably did it using https://github.com/rails/cssbundling-rails and/or https://github.com/rails/jsbundling-rails.

[BarnabeD]

@mwala-zm After following the upgrade steps, you should have moved stylesheets/application.tailwind.css to /tailwind/application.cs, so you need to update package.json to update the new path, like this :

"scripts": {
    "build": "esbuild app/javascript/*.* --bundle --sourcemap --format=esm --outdir=app/assets/builds --public-path=/assets",
-    "build:css": "tailwindcss -i ./app/assets/stylesheets/application.tailwind.css -o ./app/assets/builds/application.css --minify",
+    "build:css": "tailwindcss -i ./app/assets/tailwind/application.css -o ./app/assets/builds/application.css --minify"
}

[flavorjones]

Just released v4.0.0! Happy coding, everybody. Release v4.0.0 / 2025-02-01 · rails/tailwindcss-rails

[Chadh13]

Upgraded to this yesterday. Everything is running well locally. When attempting to deploy to heroku, the build/release phase fails due to some issue within rake assets:precompile

remote: -----> Detecting rake tasks
remote: -----> Preparing app for Rails asset pipeline
remote: cp: warning: behavior of -n is non-portable and may change in future; use --update=none instead
remote:        Running: rake assets:precompile
remote:        I, [2025-02-03T07:26:25.795837 #1607]  INFO -- honeybadger: ** [Honeybadger] Reporting error id=d37036e7-a169-4413-a3c7-352430b61d56 level=1 pid=1607
remote:        rake aborted!
remote:        Command failed with exit 1: /tmp/build_5badea3e/vendor/bundle/ruby/3.2.0/gems/tailwindcss-ruby-4.0.3-x86_64-linux-gnu/exe/x86_64-linux-gnu/tailwindcss
remote:        /tmp/build_5badea3e/vendor/bundle/ruby/3.2.0/gems/tailwindcss-rails-4.0.0/lib/tasks/build.rake:7:in `system'
remote:        /tmp/build_5badea3e/vendor/bundle/ruby/3.2.0/gems/tailwindcss-rails-4.0.0/lib/tasks/build.rake:7:in `block (2 levels) in <main>'
remote:        Tasks: TOP => assets:precompile => tailwindcss:build
remote:        (See full trace by running task with --trace)
remote:        I, [2025-02-03T07:26:25.841930 #1607]  INFO -- honeybadger: ** [Honeybadger] Success ⚡
remote:
remote:  !
remote:  !     Precompiling assets failed.
remote:  !
remote:  !     Push rejected, failed to compile Ruby app.
remote:
remote:  !     Push failed
remote: Verifying deploy...

I've got an old (>10 years old) rails app that started on probably Rails 3 or 4 and has been progressively upgraded over the years.

Our Heroku app is running on the heroku-24 stack has these buildpacks

It's not yet clear to me why it's failing on heroku when it builds and compiles normally locally. The error points to this LoC https://github.com/rails/tailwindcss-rails/blob/main/lib/tasks/build.rake#L7. Given the command that failed, my best guess at the moment is some sort of... hardware incompatibility? (I'm honestly not sure at the moment). Going to get some sleep before I take another look at this.

[Chadh13]

I shelled into our heroku server, manually installed the tailwindcss-rails gem and attempted to run the build commands from there. I wasn't able to get the commands to be found or run in any case. It seems as though it is strictly locked to the Gemfile.lock and that heroku throws out the newly installed gems almost immediately, which makes sense given that every heroku dyno is an ephemeral container that should match all other dynos that were to start.

I'm going to go ahead and open an issue in the TailwindCSS repo and submit a ticket to Heroku to see if either group has some quick insight about the failure or ideas on how to start to unpack and understand what's going on here.

[Chadh13]

Heroku's support was absolutely useless. I asked them if they could instruct me on how to run build commands of their dynos for code that their release phase rejects. They said that isn't covered by their Support Policy 🤯 . Salesforce has done a really great job with them.

Phillip said in the TailwindCSS repo issue they need more to reproduce this because it's too vague -- which I agree.

I'll keep digging around. I guess my best bet at this point leaves me with forking or vendoring this library and trying to monkeypatch the rake task with a --trace flag.

[Chadh13]

Update: I found a way to reproduce this issue locally, and ultimately tracked down the failure cause here.

Previously, we built and deployed tailwind through a yarn install. Due to switching between branches, I had the tailwind package in the .gitignored node_modules folder on my local.

When running rails tailwindcss:build on my local, the build command worked and things compiled with no issues. If I removed the node modules folder, the build command would start to fail.

Here is what rails tailwindcss:build --trace looks like when tailwindcss is installed through the gem

rails tailwindcss:build --trace
** Invoke tailwindcss:build (first_time)
** Invoke environment (first_time)
** Execute environment
** Execute tailwindcss:build
bin/rails aborted!
Command failed with exit 1: .rvm/gems/ruby-3.2.2@ssa/gems/tailwindcss-ruby-4.0.4-arm64-darwin/exe/arm64-darwin/tailwindcss
.rvm/gems/ruby-3.2.2@ssa/gems/tailwindcss-rails-4.0.0/lib/tasks/build.rake:7:in `system'
.rvm/gems/ruby-3.2.2@ssa/gems/tailwindcss-rails-4.0.0/lib/tasks/build.rake:7:in `block (2 levels) in <main>'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/task.rb:281:in `block in execute'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/task.rb:281:in `each'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/task.rb:281:in `execute'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/task.rb:219:in `block in invoke_with_call_chain'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/task.rb:199:in `synchronize'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/task.rb:199:in `invoke_with_call_chain'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/task.rb:188:in `invoke'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/application.rb:188:in `invoke_task'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/application.rb:138:in `block (2 levels) in top_level'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/application.rb:138:in `each'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/application.rb:138:in `block in top_level'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/application.rb:147:in `run_with_threads'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/application.rb:132:in `top_level'
.rvm/gems/ruby-3.2.2@ssa/gems/railties-7.2.2.1/lib/rails/commands/rake/rake_command.rb:27:in `block (2 levels) in perform'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/application.rb:214:in `standard_exception_handling'
.rvm/gems/ruby-3.2.2@ssa/gems/railties-7.2.2.1/lib/rails/commands/rake/rake_command.rb:27:in `block in perform'
.rvm/gems/ruby-3.2.2@ssa/gems/railties-7.2.2.1/lib/rails/commands/rake/rake_command.rb:44:in `block in with_rake'
.rvm/gems/ruby-3.2.2@ssa/gems/rake-13.2.1/lib/rake/rake_module.rb:59:in `with_application'
.rvm/gems/ruby-3.2.2@ssa/gems/railties-7.2.2.1/lib/rails/commands/rake/rake_command.rb:41:in `with_rake'
.rvm/gems/ruby-3.2.2@ssa/gems/railties-7.2.2.1/lib/rails/commands/rake/rake_command.rb:20:in `perform'
.rvm/gems/ruby-3.2.2@ssa/gems/railties-7.2.2.1/lib/rails/command.rb:156:in `invoke_rake'
.rvm/gems/ruby-3.2.2@ssa/gems/railties-7.2.2.1/lib/rails/command.rb:73:in `block in invoke'
.rvm/gems/ruby-3.2.2@ssa/gems/railties-7.2.2.1/lib/rails/command.rb:149:in `with_argv'
.rvm/gems/ruby-3.2.2@ssa/gems/railties-7.2.2.1/lib/rails/command.rb:69:in `invoke'
.rvm/gems/ruby-3.2.2@ssa/gems/railties-7.2.2.1/lib/rails/commands.rb:18:in `<main>'
<internal:.rvm/rubies/ruby-3.2.2/lib/ruby/3.2.0/rubygems/core_ext/kernel_require.rb>:37:in `require'
<internal:.rvm/rubies/ruby-3.2.2/lib/ruby/3.2.0/rubygems/core_ext/kernel_require.rb>:37:in `require'
.rvm/gems/ruby-3.2.2@ssa/gems/bootsnap-1.18.4/lib/bootsnap/load_path_cache/core_ext/kernel_require.rb:30:in `require'
bin/rails:4:in `<main>'
Tasks: TOP => tailwindcss:build

I assumed that tailwind was being included by the gem, so this didn't quite make sense. From here, I started commenting out parts of the config files and css code to try and identify when and if it passed vs failed. After a lot of trial and error, I pinpointed the issue to the legacy tailwind.config.js file. I couldn't figure out what exactly within our config file was failing, so I decided to migrate to css variables and delete the file altogether. This resulted in successful deploys to our heroku apps.

Generally speaking, I'd suggest that we update the upgrade guide to strongly suggest that people migrate their tailwind.config.js file to CSS variables instead of trying to use @config, butI'd be happy to share my tailwind.config.js file if that would be helpful in that you may spot the specific section/items that were causing the build process to fail with the vague Command failed with exit 1.

Please let me know if and how I can be of help so that others don't also get stuck on this.

[Michoels]

I think I found the underlying problem!

I had the same issue, where my build kept crashing with exit 1 after upgrading from v3.3.1 to v4.0.4

I tracked down the problem to tailwind.config.js, in the plugins section:

// config/tailwind.config.js
{
  plugins: [
    require("@tailwindcss/forms"),
    require("@tailwindcss/aspect-ratio"),
    require("@tailwindcss/typography"),
    require("@tailwindcss/container-queries"),
  ],
}

If these plugins are not installed in package.json, then the build crashes with exit 1.

Installing the plugins with NPM fixed the build:

npm i @tailwindcss/forms @tailwindcss/aspect-ratio @tailwindcss/typography @tailwindcss/container-queries

For future proofing, I then migrated the plugins block to the new CSS-based syntax:

/* app/assets/tailwind/application.css */

@plugin "@tailwindcss/forms";
@plugin "@tailwindcss/aspect-ratio";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/container-queries";

I then deleted the block from tailwind.config.js.

Does that solve the problem for anyone else?

[dmarczal]

Hello @Michoels, thank you for the comment.

This worked for me. When I commented out the plugins section in tailwind.config.js, the command bin/rails tailwindcss:build worked as expected with the upgraded steps.

Moving them to app/assets/tailwind/application.css kept it working.

Thanks.

[sarrietav-dev]

Hello, team!

When I create a new Rails app and run ./bin/dev, live reload doesn't work when I add a new class to any element in any view. I've also tried running ./bin/dev and ./bin/rails tailwindcss:watch, but the issue persists.

[BarnabeD]

I don't think brand new rails app are yet on tailwind V4.
I think you need to follow upgrade steps or pin gem "tailwindcss-ruby", "3.4.13"

[sarrietav-dev]

That's unfortunate. Is there something I can do to help?

[flavorjones]

@sarrietav-dev I'm sorry you're having problems.

Please note that new Rails apps will indeed use v4 unless you explicitly update your Gemfile to use v3. (cc @BarnabeD please update your mental model, thanks.)

"Live reload" is not a thing this gem does -- that term is usually used to communicate live updates in a browser -- however I assume you mean "live rebuild" as described in the README. I'm not trying to be pedantic, I'm just making sure we agree on a description of the problem so that I can better help you.

Unfortunately, I can't reproduce any issues with live rebuilds, and so I need your help to understand specifically how your project is configured, what you're doing, and what you're seeing that caused you to comment here.

It's probably best if you open a new issue since in any case what you're describing isn't related to a "v4 upgrade experience".

[sarrietav-dev]

Thanks for the quick response, @flavorjones. I appreciate the clarification! I'll open a new issue with detailed, reproducible steps to help diagnose the problem.

[MatheusRich]

If you were using plugins like typography or forms, don't forget to add them to app/assets/tailwind/application.css:

@plugin "@tailwindcss/forms";

[wfarr]

Looks like Tailwind 4.0.9 fixed issues that were requiring folks to introduce node_modules and such as a dependency to satisfy plugin resolution. This makes plugin imports in the JS config work again w/ just the standalone CLI. This is available in in tailwindcss-ruby as of yesterday:

ref: https://github.com/tailwindlabs/tailwindcss/releases/tag/v4.0.9
ref: tailwindlabs/tailwindcss#15934

[flavorjones]

@wfarr Thanks, I have not had time to investigate. If it's top of mind for you and you have a few minutes, can you send a PR suggesting updates to the README?

[matt17r]

I have some fairly simple Rails 8 apps that use Tailwind 4, importmaps and SQLite in production with a key focus on ease of maintenance and deployment. I don't have npm or yarn installed and I didn't want to install them just to run the upgrade tool so I had a go at doing it myself in one of my repos.

It took 52 minutes from first commit to last commit while figuring it out as I went, manually copying the steps in the gem upgrade script then manually updating deprecated classes in the tailwind upgrade guide. I'm no guru and I may have missed things but here's my experience report:

1. Start a new branch
2. Update gem (for me this meant unpinning 3.3.1 and running bundle update tailwindcss-rails)
3. Create app/assets/tailwind/application.css (containing a single line, @import "tailwindcss";)
4. Delete app/assets/stylesheets/application.tailwind.css (I didn't have any customisations, just the usual @tailwind base;, ... components and ... utilities which @import "tailwindcss"; replaces)
5. Remove reference to inter-font from app layout(s) (<%= stylesheet_link_tag "tailwind", "inter-font", "data-turbo-track": "reload" %>
6. Delete config/tailwind.config.js (at first I was just going to remove the defaultTheme lines but as far as I could tell, the only reason the file existed was to add the font "Inter var" to the default theme)
7. Search through my codebase for deprecated classes. For me it was just:

• outline-none to outline-hidden
• shadow to shadow-sm
• rounded-sm to rounded-xs
• border to border border-gray-200

8. I had some fancy gradients from the Tailwind UI Tailwind Plus Radiant theme that had to be updated but weren't mentioned in the Tailwind CSS upgrade docs.

Other tip... to search for deprecated classed I searched for class-name and class-name". That was mostly sufficient but you might need to expand that to include a leading space or " for ring to avoid a whole lot of false positives for string...
ring, ring", "ring and "ring"