tailwindcss-rails README（翻訳）

Tailwind CSS for Rails

Tailwind CSSはユーティリティファーストのCSSフレームワークです。flexやpt-4やtext-centerやrotate-90といったCSSクラスが同梱されており、マークアップ内で直接これらを組み合わせてあらゆるデザインを構築できます。

🔗 インストール

Rails 7では、新規アプリケーションの生成時に--css tailwindを指定することでTailwind CSSを事前設定できます。Tailwindを後から追加する場合は以下を実行する必要があります。

1. ./bin/bundle add tailwindcss-railsを実行
2. ./bin/rails tailwindcss:installを実行

このtailwindcss-rails gemは、Tailwind CLI実行可能ファイルをインストールするためにtailwindcss-ruby gemに依存しています。

🔗 特定バージョンのtailwindcssを選択する

tailwindcss-ruby gemは、このtailwindcss-rails gemのフローティング依存関係として宣言されているため、デフォルトでは最新の安定バージョンが取得されます。ただし、アプリケーションのGemfileで以下のようにそのgemを近いバージョンに固定することで、特定のバージョンのTailwind CSSを選択できます。

gem "tailwindcss-rails"

# tailwindcssバージョンを3.4.13に固定する
gem "tailwindcss-ruby", "3.4.13"

🔗 ローカルインストールされたtailwindcssを使う

必要に応じて、npmベースのローカルインストールも利用できます。詳しくはtailwindcss-rubyを参照してください。

🔗 アプリケーションのTailwindをv3からv4にアップグレードする

このtailwindcss-rails gem v4.xは、アプリケーションのアップグレードに役立つ機能も含め、Tailwind v4で動作するように更新されています。

Tailwind CSS v4のアップグレードの完全な説明はこのREADMEの範囲外であるため、既存の大規模アプリのアップグレードに着手する前に、公式の Tailwind CSS v4 アップグレード ガイドを読んでおくことが強く推奨されます。

このtailwindcss-rails gemは、以下のような一部のアップグレード作業を支援します。

• このgemのv4における重大な変更に対応するために、生成されたファイルの一部を更新する。
• Tailwind CSS v4の規約を満たすために、ローカルプロジェクトファイルの一部を更新する。
• Tailwind本家のv4アップグレードツールの実行を試みる。

🔗 v4へのアップグレードは「必須ではありません」

v4へのアップグレードは必須ではない点にご注意ください。今すぐv4に移行したくない場合や、移行中に問題が発生した場合は、当分の間Tailwind CSS v3を引き続き利用できます。

アップグレードしたくない場合は、アプリケーションのtailwindcss-rails gemを以下のようにv3.3.1に固定します。

# Gemfile
gem "tailwindcss-rails", "~> 3.3.1" # tailwindcss-rubyをv3に推移的に固定する

使っているtailwindcss-rails gemのバージョンが3.3.0以下の場合は、以下のようにtailwindcss-railsとtailwindcss-rubyを両方とも固定してください。

# Gemfile
gem "tailwindcss-rails", "~> 3.3"
gem "tailwindcss-ruby", "~> 3.4" # tailwindcss-rails <= 3.3.0の場合のみ必要

🔗 アップグレード手順

最初に、tailwindcss-railsをv4.0.0以上に更新します。これにより、tailwindcss-rubyもv4に推移的に依存するようになります。

# Gemfile
gem "tailwindcss-rails", "~> 4.0" # tailwindcss-rubyを推移的にv4に固定する

app/assets/stylesheets/application.tailwind.cssにインポートされる既存のCSSファイルへのパス参照を以下のように更新して、ファイルがapp/assets/tailwind/application.cssに移動されたときに参照が解決されるようにします。

-@import "pagy.css";
+@import "../stylesheets/pagy.css";

（オプション）TailwindのCSSクラス名をv4に移行する場合は、後述の「v4 CSSクラス名への更新」を行ってから次に進んでください。

次に、bin/rails tailwindcss:upgradeを実行します。
これにより、Tailwind公式のアップグレードツールの実行が試行されます。このツールを実行するにはnpxが必要です。これは1回限りの操作ですが、アップグレードを成功させるために強く推奨されます。

$ bin/rails tailwindcss:upgrade
       apply  /path/to/tailwindcss-rails/lib/install/upgrade_tailwindcss.rb
  Removing references to 'defaultTheme' from /home/user/myapp/config/tailwind.config.js
        gsub    config/tailwind.config.js
  Strip Inter font CSS from application layout
        gsub    app/views/layouts/application.html.erb
  Remove unnecessary stylesheet_link_tag from application layout
        gsub    app/views/layouts/application.html.erb
  Moving /home/user/myapp/app/assets/stylesheets/application.tailwind.css to /home/user/myapp/app/assets/tailwind/application.css
      create    app/assets/tailwind/application.css
      remove    app/assets/stylesheets/application.tailwind.css
10.9.0
  Running the upstream Tailwind CSS upgrader
         run    npx @tailwindcss/upgrade@next --force --config /home/user/myapp/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/tailwind/application.css`
│ Migrating JavaScript configuration files…
│ ↳ The configuration file at `./config/tailwind.config.js` could not be automatically migrated to the new CSS
│   configuration format, so your CSS has been updated to load your existing configuration file.
│ Migrating templates…
│ ↳ Migrated templates for configuration file: `./config/tailwind.config.js`
│ Migrating stylesheets…
│ ↳ Migrated stylesheet: `./app/assets/tailwind/application.css`
│ ↳ No PostCSS config found, skipping migration.
│ Updating dependencies…
│ Could not detect a package manager. Please manually update `tailwindcss` to v4.
│ Verify the changes and commit them to your repository.
  Compile initial Tailwind build
         run    rails tailwindcss:build from "."
≈ tailwindcss v4.0.0
Done in 56ms
         run  bundle install --quiet

成功しない場合は、Tailwind設定がカスタマイズされている可能性があります。この場合、アプリケーションが確実にアップグレードされるように作業を行う必要があります。Tailwind公式のアップグレードガイドをよく読んでから、後述の追加手順「v4 CSSクラス名への更新」に沿って作業してみてください。

🔗 アップグレードのトラブルシューティング

アップグレードで問題が生じた場合は、以下のディスカッションを確認してください。

参考: TailwindCSS v4 - upgrade experience report · rails/tailwindcss-rails · Discussion #450

アップグレードタスクで対処されていない既知のケースがいくつかあります。

• TailwindプラグインをJavaScriptツールを経由せずに利用しているアプリケーションでは、以下に示すアップグレード手順を実行するとtailwind.config.jsファイルの完全な移行に失敗する可能性があります。
  理由は、Tailwind本家のアップグレードツールでは、インストールされているTailwindプラグインがJavaScriptパッケージマネージャから利用できる必要があるためです。
  Tailwind本家のアップグレードツールを実行中にエラーが発生した場合は、後述する追加手順「v4 CSSクラス名への更新」を試してください。これは、必要なパッケージを（一時的に）インストールして、作業終了後にクリーンアップするのに役立ちます。

今後アップグレードプロセスについては追って改善を試みる予定ですが、現時点ではアップグレード中に何らかの手動作業が必要になる可能性があります。

🔗 Tailwind CSSクラスをv4向けに更新する

いくつかの追加作業を手動で行っておくことで、Tailwind公式のアップグレードツールがアプリケーションのCSSクラス名をv4の規約に更新するようになります。このオプション手順を実行するには、JavaScriptツールチェインを利用可能にしておく必要があります。

Tailwind公式のアップグレードツールがnode_modules/以下のファイルにアクセスしないようにするには、.gitignoreファイルに以下の行を追加します。

/node_modules

プロジェクトのrootディレクトリにpackage.jsonファイルを以下の内容で作成します。

{
  "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...
  }
}

npm install（yarnを使っている場合はyarn install）を実行します。

config/tailwind.config.jsを更新します。以下のようにcontent部分を一時的に変更して、すべてのパスに.を追加し、設定ファイルに対する相対パスが使われるようにします。

  content: [
    '../public/*.html',
    '../app/helpers/**/*.rb',
    '../app/javascript/**/*.js',
    '../app/views/**/*.{erb,haml,html,slim}'
  ],

（参照するすべてのパスに.を追加するだけです）

上記の指示に沿ってTailwind公式のアップグレードツールを実行します。

ツールが正常に実行されたら、一時設定をクリーンアップします。

• 以下を削除します。.gitignoreの/node_modulesも削除します。
  • package.jsonファイル
  • node_modules/ディレクトリ
  • package-lock.json（またはyarn.lock）
• 自分たちのCSSファイルを開いて以下の行を削除します（存在する場合）。

@plugin '@tailwindcss/container-queries';

• config/tailwind.config.jsへの変更を元に戻します（パスが再びアプリケーションのrootに相対的になるようにします）。

🔗 Tailwindcssで開発する

🔗 設定とコマンド

🔗 入力ファイル: app/assets/tailwind/application.css

tailwindcss:installタスクを実行すると、Tailwind入力ファイルをapp/assets/tailwind/application.cssに生成します。この入力ファイルでは、使いたいプラグインをインポートしたり、カスタム@applyルールを設定したりできます。

注意: v4では、このファイルは以下のように変更されました。tailwindcss:upgradeタスクを実行するとこの変更・リネームが行われます。

• 変更前: app/assets/stylesheets/application.tailwind.css
• 変更後: app/assets/tailwind/application.css

🔗 出力ファイル: app/assets/builds/tailwind.css

rails tailwindcss:buildタスクを実行すると、入力ファイルを用いてapp/assets/builds/tailwind.cssファイルに出力が生成されます。これが出力CSSとして最終的にアプリに含められます。

🔗 コマンド

このtailwindcss-rails gemでは、さまざまなRailsタスクが利用可能になります。オプションが複数使えるタスクもあり、タスクを組み合わせることも可能です。

概要:

bin/rails tailwindcss:install

Tailwindの設定ファイルと出力ファイル、およびProcfile.devをインストールします。

bin/rails tailwindcss:build

出力ファイルを生成します。

bin/rails tailwindcss:build[debug]

最小化（minify）なしの出力を生成します。

bin/rails tailwindcss:watch

開発中のライブリビルドを開始し、ファイルが変更されると出力を生成します。

bin/rails tailwindcss:watch[debug]

最小化なしの出力を生成します。

bin/rails tailwindcss:watch[poll]

ファイルシステムイベントが使えないシステム用

bin/rails tailwindcss:watch[always]

TTYのないシステム用（一部のDockerコンテナなど）

上記タスクのオプションはrails tailwindcss:watch[debug,poll]のように組み合わせも可能です。

このtailwindcss-rails gemは、rails serverコマンドを実行するときにライブ再構築プロセスを管理するためのPumaプラグインも提供します（後述の「ライブリビルド」を参照）。

また、rails serverコマンドとライブリビルドプロセスの両方を実行するProcfile.devファイルも生成します（後述の「ライブリビルド」を参照）。

🔗 production向けビルド

tailwindcss:buildコマンドは自動的にassets:precompileにアタッチされるので、Tailwind出力ファイルの生成が完了してからアセットパイプラインがファイルをダイジェスト化します。

🔗 テスト向けビルド

tailwindcss:buildコマンドは自動的にtest:prepare rakeタスクにアタッチされます。このtest:prepareタスクは、テストコマンドの前に実行されます。CI環境でbin/rails testを実行すると、テスト実行前にTailwindの出力が生成されます。

🔗 最小化されていないアセットでビルドする

アセットを最小化したくない場合は、以下のようにrakeタスクにdebug引数を渡します。

• rails tailwindcss:build[debug]、または
• rails tailwindcss:watch[debug]

🔗 ライブリビルド

アプリケーションの開発中、Tailwindを「ウォッチ」モードで実行することで、ファイルの変更が生成されたCSS出力に自動的に反映されるようにできます。これは以下のようなさまざまな方法で実行できます。

• tailwindcss-rails gem用のPumaプラグインを使ってrails serverコマンドに「ウォッチ」モードを統合する
• rails tailwindcss:watchを別プロセスとして実行する
• bin/devコマンドを実行する（この場合Foremanが使われます）

🔗 Pumaプラグイン

このtailwindcss-rails gemにはPumaプラグインが同梱されています。これを使うにはpuma.rb設定ファイルに以下の行を追加します。

plugin :tailwindcss if ENV.fetch("RAILS_ENV", "development") == "development"

これで、rails server（またはpuma）を実行すると、バックグラウンドでTailwindのウォッチプロセスが実行されます。

🔗 rails tailwindcss:watchを実行する

このコマンドは柔軟で、いくつかの異なるオプションを指定して実行できます。

ファイルシステムイベントのサポートが完全でないシステムでrails tailwindcss:watchを実行する場合は、以下のようにタスクにpoll引数を渡すことで、tailwindcssにポーリングを使うよう指示します。

rails tailwindcss:watch[poll]

（bin/devコマンドを使う場合は、Procfile.devを変更してpollオプションを使うようにする必要があります）

rails tailwindcss:watchコマンドをDockerコンテナ内のプロセスとして実行している場合は、適切なコンテナのdocker-compose.ymlファイルでtty: trueを設定して、監視プロセスを実行し続けるようにします。

ttyのないDockerコンテナ内で rails tailwindcss:watchを実行している場合は、rails tailwindcss:watch[always]のようにタスクにalways引数を渡します。これで、stdinが閉じている場合でもファイルウォッチャーが閉じないようにtailwindcssに指示されます（bin/devコマンドを使う場合は、Procfile.devを変更する必要があります）。

🔗 Foreman

bin/devコマンドでRailsサーバーを実行すると、Foremanが呼び出され、developmenntモードでProcfile.devファイルに基づいてTailwindの監視プロセスとRailsサーバーの両方が起動されます。

🔗 PostCSSを使う場合

PostCSSをプリプロセッサとして使う場合は、プロジェクトのrootディレクトリにカスタムのpostcss.config.jsを作成しておくと、Tailwindによって自動的に読み込まれます。

たとえば、ネストを有効にするには以下のようにします。

// postcss.config.js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  }
}

注意: PostCSSは独自の前提条件を必要とするJavaScriptツールであることにご注意ください。tailwindcss-railsは、デフォルトではJavaScriptツールを必要としないため、PostCSSを使うには、以下のようなプラグイン依存関係を含むpackage.jsonと、パッケージマネージャ（yarnやnpmなど）が必要です。

// package.json
{
  "name": "my app",
  "private": true,
  "dependencies": {
    "@tailwindcss/postcss": "^4.0.0",
    "tailwindcss": "^4.0.0",
    "postcss": "^8.5.1"
  }
}

これでyarnまたはnpmを実行して依存関係をインストールできるようになります。

🔗 入力ファイルや出力ファイルをカスタマイズする

入力ファイルや出力ファイルをカスタマイズする必要がある場合は、bundle exec tailwindcssを実行してプラットフォーム固有の実行可能ファイルにアクセスすることで、独自のビルドオプションを指定できます。

🔗 トラブルシューティング

ユーザーがよく遭遇するいくつかの問題点を以下に記載します。

🔗 Pumaプラグインを使うとターミナルベースのデバッグツール（IRB、Pry、ruby/debugなど）でキー入力が失われたりハングしたりする

この問題は解決済みです。tailwindcss-railsをv2.4.1以降のバージョンにアップグレードすることで問題を回避できます。

🔗 Dockerコンテナ内で実行すると途中で終了する

rails tailwindcss:watchコマンドをDockerコンテナ内のプロセスとして実行している場合は、適切なコンテナのdocker-compose.ymlでtty: trueを設定して、監視プロセスが終了しないようにしてください。

ttyのないDockerコンテナ内でrails tailwindcss:watchを実行している場合は、rails tailwindcss:watch[always]のようにalways引数をタスクに渡すことで、stdinが閉じている場合でもウォッチャーを終了しないようtailwindcssに指示します（bin/devコマンドを使う場合は、Procfile.devを変更する必要があります）。

🔗 sassc-railsとコンフリクトする

Tailwindで用いられている最新のCSS機能は、Rails 6のGemfileにデフォルトでインクルードされているsassc-rails拡張では認識されません。SassC::SyntaxErrorのようなエラーを回避するには、sassc-rails gemを削除する必要があります。

🔗 CSSクラス名は完全な形で書くこと

Tailwindが正常に動作するためには、CSSクラス名を完全な形で記述する必要があります。コンテンツファイルに存在しないクラス名や、プログラムで組み立てられたクラス名をTailwindで生成する必要がある場合は、Tailwindのsafelistオプションをお使いください。

🔗 ERROR: Cannot find the tailwindcss executable for <サポート対象プラットフォーム>

詳しくはtailwindcss-rubyを参照してください。

🔗 アセットパイプラインのアセットを使うには

Railsを使っていると、アセットパイプラインのアセットからフィンガープリントを取得したくなることがあります（Railsガイド）が、Tailwindはアセットパイプラインのアセットについては関知しません。

アセットパイプラインのアセットを使いたい場合は以下のようにurl(image.svg)をお使いください。Sprockets v3.3.0以降（#476）はurl(image.svg)が/path/to/assets/image-7801e7538c6f1cc57aa75a5876ab0cac.svgのように自動的に書き換えられ、出力CSSにそれらのアセットへの正しいパスが含まれるようになります。

module.exports = {
    theme: {
        extend: {
            backgroundImage: {
                'image': "url('image.svg')"
            }
        }
    }
}

以下のようにインラインで書くこともできます。

<section class="bg-[url('image.svg')]">Has the image as it's background</section>

🔗 ライセンス

Tailwind for Rails is released under the MIT License.

関連記事

cssbundling-rails README（翻訳）

Propshaft gem README（翻訳）