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

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

[EricGusmao]

A quick update from my side. I deployed to prod, only using the @plugin directive - without any package manager and the plugins work just fine. You do not need to use any JS package manager. I only use this gem, nothing else. Hosted and container built on heroku

All tailwind first-party plugins are bundled with the standalone CLI, that's why it must work fine.

[EricGusmao]

@flavorjones updated this guide to reflect the new discoveries.

[flavorjones]

@EricGusmao OK, removed the plugins note from the README.

[EricGusmao]

@flavorjones should I open a PR to add this guide to README? or is it better to have it scripted ?

[flavorjones]

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

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

[flavorjones]

@mwala-zm I'm not sure what issue you're referring to, can you please help us understand what problem you're having that you're trying to solve?

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

[flavorjones]

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