2月半ば過ぎの頃、Railsアプリでbundle updateを実行したところ突然Tailwindcssがエラーで動かなくなりました。
$ bundle update
Fetching gem metadata from https://rubygems.org/..........
Resolving dependencies...
Using logger 1.6.6 (was 1.6.5)
Fetching zeitwerk 2.7.2 (was 2.7.1)
Fetching msgpack 1.8.0 (was 1.7.5)
Fetching stringio 3.1.5 (was 3.1.2)
Fetching rack 3.1.10 (was 3.1.8)
Fetching rexml 3.4.1 (was 3.4.0)
Fetching mime-types-data 3.2025.0220 (was 3.2025.0107)
Fetching json 2.10.1 (was 2.9.1)
Fetching lint_roller 1.1.0
Installing zeitwerk 2.7.2 (was 2.7.1)
Fetching sqlite3 2.6.0 (aarch64-linux-gnu) (was 2.5.0)
Installing msgpack 1.8.0 (was 1.7.5) with native extensions
Installing stringio 3.1.5 (was 3.1.2) with native extensions
Installing rack 3.1.10 (was 3.1.8)
Fetching tailwindcss-ruby 4.0.7 (aarch64-linux-gnu) (was 3.4.17)
Installing rexml 3.4.1 (was 3.4.0)
Fetching thruster 0.1.11 (aarch64-linux) (was 0.1.10)
Installing mime-types-data 3.2025.0220 (was 3.2025.0107)
Fetching nokogiri 1.18.3 (aarch64-linux-gnu) (was 1.18.2)
Installing json 2.10.1 (was 2.9.1) with native extensions
Installing lint_roller 1.1.0
Fetching parser 3.3.7.1 (was 3.3.7.0)
Installing sqlite3 2.6.0 (aarch64-linux-gnu) (was 2.5.0)
Fetching net-imap 0.5.6 (was 0.5.5)
Fetching net-smtp 0.5.1 (was 0.5.0)
Fetching sshkit 1.24.0 (was 1.23.2)
Fetching webmock 3.25.0 (was 3.24.0)
Installing net-smtp 0.5.1 (was 0.5.0)
Installing tailwindcss-ruby 4.0.7 (aarch64-linux-gnu) (was 3.4.17)
Installing net-imap 0.5.6 (was 0.5.5)
Installing webmock 3.25.0 (was 3.24.0)
Installing sshkit 1.24.0 (was 1.23.2)
Fetching playwright-ruby-client 1.50.1 (was 1.49.0)
Installing thruster 0.1.11 (aarch64-linux) (was 0.1.10)
Installing playwright-ruby-client 1.50.1 (was 1.49.0)
Fetching rdoc 6.12.0 (was 6.11.0)
Installing parser 3.3.7.1 (was 3.3.7.0)
Fetching kamal 2.5.2 (was 2.4.0)
Installing kamal 2.5.2 (was 2.4.0)
Installing rdoc 6.12.0 (was 6.11.0)
Installing nokogiri 1.18.3 (aarch64-linux-gnu) (was 1.18.2)
Fetching rubocop 1.72.2 (was 1.71.0)
Installing rubocop 1.72.2 (was 1.71.0)
Fetching solid_cache 1.0.7 (was 1.0.6)
Installing solid_cache 1.0.7 (was 1.0.6)
Fetching rubocop-minitest 0.37.1 (was 0.36.0)
Fetching rubocop-performance 1.24.0 (was 1.23.1)
Fetching rubocop-rails 2.30.1 (was 2.29.1)
Installing rubocop-minitest 0.37.1 (was 0.36.0)
Installing rubocop-performance 1.24.0 (was 1.23.1)
Installing rubocop-rails 2.30.1 (was 2.29.1)
Fetching tailwindcss-rails 4.1.0 (was 3.3.1)
Installing tailwindcss-rails 4.1.0 (was 3.3.1)
Bundle updated!
Post-install message from solid_cache:
Upgrading from Solid Cache v0.3 or earlier? There are new database migrations in v0.4.
See https://github.com/rails/solid_cache/blob/main/upgrading_to_version_0.4.x.md for upgrade instructions.
Post-install message from tailwindcss-rails:
== Upgrading to Tailwind CSS v4 ==
If you are upgrading to tailwindcss-rails 4.x, please read the upgrade guide at:
https://github.com/rails/tailwindcss-rails/blob/main/README.md#upgrading-your-application-from-tailwind-v3-to-v4
If you're not ready to upgrade yet, please pin to version 3 in your Gemfile:
gem "tailwindcss-rails", "~> 3.3.1"
$ bin/rails test
≈ tailwindcss v4.0.7
Specified input file `./app/assets/tailwind/application.css` does not exist.
bin/rails aborted!
Command failed with exit 1: /home/vscode/.rbenv/versions/3.4.1/lib/ruby/gems/3.4.0/gems/tailwindcss-ruby-4.0.7-aarch64-linux-gnu/exe/aarch64-linux-gnu/tailwindcss
Tasks: TOP => test:prepare => tailwindcss:build
(See full trace by running task with --trace)
調べてみたところ、最近Tailwindcssがv4にメジャーバージョンアップされていて、それに伴いtailwindcss-rails gemも大幅に更新されていることを知りました。
参考: Tailwind CSS v4.0 - Tailwind CSS
参考: Upgrade guide - Getting started - Tailwind CSS
また、昨年10月に、tailwindcss-railsからtailwindcss-rubyというgemが新たに切り出されていました↓。これはtailwindcss-railsのgemspecで依存関係として追加されています。
これに伴い、tailwindcss-rails READMEも大幅に更新されてv4へのアップグレード方法が追加されたため、以下の日本語訳にもアップグレード方法を反映しました↓。
なお、同READMEにも書かれているように、tailwindcss-railsのv4へのアップグレードは少なくとも現時点では必須ではありません。当面v3のままにしておいてもよいとのことです。
Tailwindcss v4.0の主な変更点
Tailwindcss v4.0の主な変更点については以下の記事にひととおりまとまっていますので、そちらをご覧ください。
ここでは、変更点のうちtailwindcss-railsに影響するbreaking changesにのみ注目していきます。
1. インストール方法が変更された
Tailwind v4はゼロコンフィグを指向するようになり、基本的に従来のconfig/tailwindcss.config.jsファイルを使わなくなりました。
具体的には、従来コンフィグファイルに書いていた設定を、CSSに直接@import "tailwindcss";と書けば済むようになり、プラグインなしでコンテナクエリなどが使えるようになったそうです（そのためTailwind v3のcorePluginsは使えなくなりました）。
つまり、Tailwind v4でこのあたりが変更されたために、tailwindcss-railsでもbreaking changesが発生したということになります。
従来tailwindcss.config.jsで書かれていたものは、以下のようにCSSで書く形に変更することになります。当然ながら書式は大きく変わります（移行ツールである程度対応できるようですが）。
@import "tailwindcss";
@theme {
--font-display: "Satoshi", "sans-serif";
--breakpoint-3xl: 1920px;
--color-avocado-100: oklch(0.99 0 0);
--color-avocado-200: oklch(0.98 0.04 113.22);
--color-avocado-300: oklch(0.94 0.11 115.03);
--color-avocado-400: oklch(0.92 0.19 114.08);
--color-avocado-500: oklch(0.84 0.18 117.33);
--color-avocado-600: oklch(0.53 0.12 118.34);
--ease-fluid: cubic-bezier(0.3, 0, 0, 1);
--ease-snappy: cubic-bezier(0.2, 0, 0, 1);
/* ... */
}
CSSに以下のように書けば、従来通りtailwind.config.jsを明示的に指定できますが、おそらく移行のための処置なので、将来どうなるかわかりません。
@import "tailwindcss";
@config "YOUR_PATH/tailwind.config.js";
2: tailwindcss-railsファイルの配置が変更された
tailwindcss-railsがv3からv4に変わったことで、ファイル編成も以下のように変わります。
stylesheets/ディレクトリの下にあったapplication.tailwind.cssが、tailwind/ディレクトリの下に移動してapplication.cssにリネームされた。- tailwind.config.jsが生成されなくなった。
.
├── app
│ ├── assets
├── builds
│ └── tailwind.css
├── images
├── stylesheets
│ └── application.css
- ├── application.tailwind.css
+ └── tailwind
+ └── application.css
...
├── config
│ ├── application.rb
│ ├── boot.rb
│ ├── cable.yml
│ ├── cache.yml
│ ├── credentials.yml.enc
│ ├── database.yml
│ ├── deploy.yml
│ ├── environment.rb
│ ├── environments
│ ├── importmap.rb
│ ├── initializers
│ ├── locales
│ ├── master.key
│ ├── puma.rb
│ ├── queue.yml
│ ├── recurring.yml
│ └── routes.rb
-│ └── tailwind.config.js
...
今後は、基本的にこのtailwind/application.cssにコンフィグを書いていくことになります。
なお、新規Railsアプリで-c tailwindを指定して生成した直後のtailwind/application.cssには、以下しか書かれていません。従来config/tailwind.config.jsに書いていたカスタム設定はこのファイルに移行することになります。
/* v4の場合 */
@import "tailwindcss";
v3では以下でした。
/* v3の場合 */
@tailwind base;
@tailwind components;
@tailwind utilities;
/*
@layer components {
.btn-primary {
@apply py-2 px-4 bg-blue-200;
}
}
*/
また、tailwindcss-rails v4ではレイアウトファイルにtailwind用のstylesheet_link_tagが含まれなくなります。
<!-- app/views/layouts/application.html.erb -->
<%# Includes all stylesheet files in app/assets/stylesheets %>
- <%= stylesheet_link_tag "tailwind", "inter-font", "data-turbo-track": "reload" %>
+
3: 非推奨化されたクラス、リネームされたクラス
Tailwind v4ではTailwindクラス命名の細かな不整合を解消したようです。
そのため、既存のTailwindクラスで非推奨になったものは修正することになります。
Tailwind v4では、これを含めて多くのbreaking changesがあります。
Tailwind公式のv3→v4アップグレードツールとしてnpx @tailwindcss/upgradeが提供されていて、これらのリネームを行ってくれるようです（なおtailwindcss-railsのアップグレード手順でbin/rails tailwindcss:upgradeを実行すると、このnpx @tailwindcss/upgradeも実行されます）。
ただしこのツールによって複雑なものがうまくリネームされるかどうかは、たぶんやってみないとわかりません（自分の場合そこまでTailwindを使い倒しているわけではないので、クラス名のリネームは発生しませんでしたが）。
importmap-railsではTailwindのサードパーティプラグインを追加できなくなる
Rails特有の事情として、近年はnpmやyarnなどを使わないimportmap-railsベースのセットアップがデフォルトになっています。
しかし上のアップグレードツールを実行するには、npx（ひいてはnpm）を使えるようにしておかなければなりません。ツールの実行が終わったら削除して構わないのですが、その分手間がかかります。
先述したように、tailwindcss-railsのアップグレード手順にも、「当面v4に無理してアップグレードしなくてもよい」と説明されています。
さらに、どうやらv4からはTailwindのプラグインはJavaScriptバンドラー（npmとかyarnとかbunなど）経由でインストールしなければならなくなったようです。つまりimportmap-rails方式ではサードパーティTailwindプラグインを追加できないということになります。
v4では本来以下のように書けばサードパーティプラグインを使えるらしいのですが、JavaScriptバンドラーのない環境（importmap-rail）では無効です（エラーにはならず単に無視されます）。
@import "tailwindcss";
@plugin "@tailwindcss/typography";
幸いv4では、従来tailwind.config.jsに書かれていた公式のプラグインがコアに取り入れられたことで記述不要になったので、プラグインを使う必要性は下がったはずです。
RailsでサードパーティのTailwindプラグインをどうしても追加したい場合は、importmap-railsをやめてjsbundling-railsとcssbundling-rails方式に切り替える必要があるでしょう。
以下の記事を見ると、プラグインがv4に対応していないと使えなさそうですが、そもそもTailwindのサードパーティプラグインがどのぐらい使われているのかわかりません（それほど必要とも思えない）。
参考: ブログを tailwindcss v4 に移行 | CodingFeline
v4では少なくともPostCSSやVite（どちらも使ったことなし）のサポートが手厚くなっているようなので、それらのプラグインについては心配しなくてよさそうではあります。