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! 🙏

[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-ruby", "~> 3.4"

[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.

[octave]

Nice! I was about to install tailwindcss-rail on a new rails 8 project, will it use version 4 or do I have to wait?

[flavorjones]

My advice is to wait a few hours until I can ship an update to this gem. We're getting close.

[flavorjones]

Please give v4.0.0.rc1 a try!

[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.

[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 [email protected] @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.

[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.

[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!!

Warning

In order to update class names in the views, PostCSS must be added.

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. Also we don’t want it to be versioned anyway)

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, and you can remove the tailwindcss dependency from package.json if you wish—it’s not needed anymore.

Important

You must keep the plugins as dependencies because Tailwind’s @plugin directive, intended for backward compatibility, expects them to be a dependency; otherwise, compilation will fail.

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!