This article shows the Tailwind 4 upgrade of the tailwindcss-rails gem.

Upgrades

1) Pointing to the correct tailwind in the Gemfile

gem 'tailwindcss-rails', "~> 4.0"

2) If you have previously pinned to a tailwindcss-ruby version, please remove it

# gem "tailwindcss-ruby", "~> 3.4"

3) In your application.tailwind.css, replace the @tailwind directive

@tailwind base;
@tailwind components;
@tailwind utilities;

4) Replace them with:

@import 'tailwindcss';

5) In your tailwind.config.js, removes the default plugins:

    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
    require('@tailwindcss/container-queries'),

6) If you are using these or other additional plugins, please ensure you import them via a package manager.

7) Bundle install/upgrade

8) Run the upgrade utility.

rails tailwindcss:upgrade

After this step, your tailwind.config.js will be removed, and your application.tailwind.css will be moved to tailwind/application.css

Tuning

1) The behavior of the class scanner has changed for ERB.

<!-- in v3, both bg-sky-100 and bg-sky-200 will be picked up. But in v4, only the former will be picked up. -->
<div class="<% if something %>bg-sky-100<% else %>bg-sky-200<% end %> px-3 py-1">test</div>

You could fix this by @apply. For example:

.category {
    @apply bg-sky-100 px-3 px-1;
}

.category.active {
    @apply bg-sky-200 px-3 px-1;
}

 Then:

<div class="category <% if something %>active<% end %>">test</div>

2) Deprecated classes:

<!-- v3 -->
<div class="bg-black bg-opacity-50"></div>

<!-- v4 -->
<div class="bg-black/50"></div>

Ref: https://tailwindcss.com/docs/upgrade-guide#removed-deprecated-utilities

3) Renamed classes:

<!-- v3 -->
<div class="rounded"></div>

<!-- v4 -->
<div class="rounded-sm"></div>

Ref: https://tailwindcss.com/docs/upgrade-guide#renamed-utilities

Full guides

1) The tailwindcss-rails gem

2) Tailwind official