tailwindcss-rails README（翻訳）

Tailwind CSS for Rails

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

🔗 インストール

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

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

このtailwindcss-rails gemには、Tailwind CSS v3フレームワークのスタンドアロン実行可能ファイルが含まれています。これらの実行ファイルはプラットフォームに依存するため、実際にはプラットフォームごとに異なるgemが存在しますが、自分が使うプラットフォームに適したgemが自動的に選択されるようになっています。

サポートされているプラットフォームは以下です。

• arm64-darwin（macos-arm64）
• x64-mingw32（windows-x64）
• x64-mingw-ucr（windows-x64）
• x86_64-darwin（macos-x64）
• x86_64-linux（linux-x64）
• aarch64-linux（linux-arm64）
• arm-linux（linux-armv7）

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

ベンダー提供のスタンドアロン実行ファイルを利用できない事情がある場合（サポートされていないプラットフォームなど）、実行可能ファイルが含まれているディレクトリへのパスをTAILWINDCSS_INSTALL_DIR環境変数 に設定することで、ローカルインストールしたtailwindcss 実行可能ファイルを利用できるようになります。

たとえば、実行可能ファイルを/node_modules/bin/tailwindcssに配置する形でtailwindcssをインストールする場合は、環境変数を以下のように設定してください。

TAILWINDCSS_INSTALL_DIR=/path/to/node_modules/bin

この設定は相対パスでも有効です。アプリの./node_modules/.bin/tailwindcssディレクトリにインストールした場合は、以下のように設定します。

TAILWINDCSS_INSTALL_DIR=node_modules/.bin

🔗 Tailwindcssで開発する

🔗 設定

Tailwindのビルドは、従来のnodeインストールでTailwindを実行する場合と同様にconfig/tailwind.config.jsファイルでカスタマイズできます。ファーストパーティのプラグインはすべてサポートされます。

インストーラは、Tailwindの入力ファイルをapp/assets/stylesheets/application.tailwind.cssに作成します。使いたいプラグインはこのファイルでインポートし、カスタムの@applyルールもこのファイルでセットアップできます。

rails tailwindcss:buildを実行すると、この入力ファイルを用いてapp/assets/builds/tailwind.cssという出力ファイルが生成されます。これがアプリにインクルードされる出力CSSです（インストーラはこれを自動で設定し、Interフォントも同様に設定します）。

🔗 production向けビルド

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

🔗 テスト向けビルド

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

🔗 アセットの自動更新

アプリケーションの開発中にTailwindを"ウォッチ"モードで実行して、変更内容を生成されるCSS出力に自動的に反映したい場合は、以下のいずれかの方法で可能です。

• rails tailwindcss:watchを別プロセスとして実行する、または
• ./bin/devを実行する（foremanを用いて、TailwindのウォッチプロセスとdevelopmentモードのRailsサーバーを両方起動します）

rails tailwindcss:watch のサポートが不十分なシステムで実行する場合は、このタスクにrails tailwindcss:watch[poll]のようにpoll引数を渡して、tailwindcssが代わりにポーリングするように指示します。。 bin/devで実行する場合は、 Procfile.devを変更する必要があります。

rails tailwindcss:watchをDockerコンテナ内のプロセスとして実行する場合は、適切なコンテナがウォッチプロセスを実行し続けるためにdocker-compose.ymlファイル内でtty: trueを指定してください。

ttyのないDockerコンテナ内でrails tailwindcss:watchコマンドを実行する場合は、rails tailwindcss:watch[always]のようにalways引数を渡すことで、stdinがクローズしたときもウォッチャーを動かし続けるようTailwindに指示します。ただしbin/devコマンドで実行する場合は、Procfile.devファイルを変更する必要があります。

🔗 最小化されていないアセットでデバッグする

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

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

なお、タスクのオプションは以下のように複数指定できます。

• rails tailwindcss:watch[debug,poll]

🔗 カスタムの入力ファイルや出力ファイル

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

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

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

🔗 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 <サポート対象プラットフォーム>

一部のユーザーから、以下のサポート対象ネイティブプラットフォームのいずれかで実行した場合にこのエラーが発生することが報告されています。

• arm64-darwin
• x64-mingw32
• x64-mingw-ucrt
• x86_64-darwin
• x86_64-linux
• aarch64-linux

🔗 対応1: BundlerのPLATFORMSをチェックする

考えられる原因のひとつは、Bundlerが現在のプラットフォーム用のネイティブgemを含める指示を受け取っていないというものです。Gemfile.lockファイルをチェックして、PLATFORMSセクション内に現在のプラットフォームが含まれているかどうかを調べてください。含まれていない場合は、以下を実行してから再度Bundlerを実行します。

bundle lock --add-platform <プラットフォーム名>

🔗 対応2: BUNDLE_FORCE_RUBY_PLATFORMをチェックする

よくあるもうひとつの原因は、BUNDLE_FORCE_RUBY_PLATFORM設定パラメータがtrueに設定されていて、Bundlerが常にその設定を用いているというものです。その場合は、以下のいずれかを実行してこの設定を削除してから再度Bundlerを実行してください。

bundle config unset force_ruby_platform
# または
bundle config set --local force_ruby_platform false

詳しくは以下のBundlerドキュメントを参照してください。

参考: Bundler: bundle config

🔗 Alpine（musl）環境でNo such file or directoryエラーが発生する

一部のユーザーが、Alpineシステム上で tailwindcssを実行するとNo such file or directoryエラーが発生すると報告しています。

🔗 対応: GNU libc compatibility（gcompat）をインストールする

これは、本家のtailwindcssバイナリ実行ファイルがGNU libcシステム上でビルドされているために、標準のmusi libcシステムと互換性がないことが原因です。

本家側の修正については#6785で提案されている状態ですが、それまでは以下のように互換ライブラリをインストールすることで回避できます。

apk add build-base gcompat

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

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.
Tailwind CSS is released under the MIT License.
The Inter font is released under the SIL Open Font License, Version 1.1.

関連記事

cssbundling-rails README（翻訳）

Propshaft gem README（翻訳）