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