Tech Racho エンジニアの「?」を「!」に。
  • Ruby / Rails関連

tailwindcss-rails README(翻訳)

概要

MITライセンスに基づいて翻訳・公開いたします。

Tailwind CSS for Rails

Tailwind CSSはユーティリティファーストのCSSフレームワークです。flexpt-4text-centerrotate-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が自動的に選択されるようになっています。サポートされるプラットフォームは以下です(セットアップがこのようになっているため、実際のgemをインストールしなければならない点にご注意ください: gemをこのGitHubリポジトリにピン留めすることはできません)。

  • Linux x64
  • macOS arm64
  • macOS x64
  • Windows x64

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にアタッチされ、Railsテストより前に実行されます。ただし現時点ではtest:*タスク(test:alltest:controllersなど)のみが該当し、test:prepareを読み込まないrails testは該当しないことにご注意ください。

アセットの自動更新

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

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

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

ファイルシステムイベントのサポートが不十分なシステム上でrails tailwindcss:watchコマンドを実行する場合は、rails tailwindcss:watch[poll]のようにpoll引数を渡して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クラス名を記述する必要があります。クラス名をプログラムで組み立ててはいけません。"text-gray-#{grade}"のような書き方は無効で、"text-gray-500"のみが有効です。

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(翻訳)


CONTACT

TechRachoでは、パートナーシップをご検討いただける方からの
ご連絡をお待ちしております。ぜひお気軽にご意見・ご相談ください。