---
title: Tailwind 4 upgrades in Rails
url: https://calvin.my/posts/tailwind-4-upgrades-in-rails
published: 2025-03-13
updated: 2026-09-17
category: Development
tags:
- Rails
- Tailwind
- Upgrade
summary: This post outlines upgrading a Rails application to Tailwind CSS 4 through the tailwindcss-rails gem. The process updates dependencies, replaces the previous stylesheet directives with a single import, removes default plugin configuration, and uses the upgrade utility to migrate files and retire the JavaScript configuration. It also highlights ERB class-scanning changes and required updates for deprecated or renamed utility classes.
---

# Tailwind 4 upgrades in Rails

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

* * *

## Upgrades

1. Pointing to the correct tailwind in the Gemfile

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

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

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

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

   ```css
   @tailwind base;
   @tailwind components;
   @tailwind utilities;
   ```

4. Replace them with:

   ```css
   @import 'tailwindcss';
   ```

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

   ```javascript
   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.

   ```bash
   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.

   ```html
   <!-- 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:

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

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

   Then:

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

2. Deprecated classes:

   ```html
   <!-- 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](https://tailwindcss.com/docs/upgrade-guide#removed-deprecated-utilities)

3. Renamed classes:

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

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

   Ref: [https://tailwindcss.com/docs/upgrade-guide#renamed-utilities](https://tailwindcss.com/docs/upgrade-guide#renamed-utilities)

* * *

## Full guides

1. The [tailwindcss-rails](https://github.com/rails/tailwindcss-rails?tab=readme-ov-file#upgrading-your-application-from-tailwind-v3-to-v4) gem

2. [Tailwind](https://tailwindcss.com/docs/upgrade-guide) official