cssbundling-rails README(翻訳)
cssbundling-rails gemは、Tailwind CSS、Bootstrap、Bulma、PostCSS、またはDart Sassを用いてCSSをバンドルおよび処理した後、Railsのアセットパイプライン経由で配信します。このgemは、新しいRailsアプリケーションで上述の好みのバンドラーを利用できるインストーラと、バンドルした出力ファイルをGitなどのソースコード管理に登録されない形でapp/assets/buildsディレクトリに保持する規約を提供します(インストーラはこのディレクトリをデフォルトで.gitignoreに追加します)。
この方法で開発を行うには、ターミナルでyarn build:css --watch
を実行してバンドラーをwatchモードで起動しておきます(puma-devなどを使っていない場合は、Railsサーバーを別のターミナルで実行してください)。また、./bin/dev
を実行すればRailsサーバーとCSSビルドウォッチャーをまとめて起動できます(jsbundling-railsを使っている場合はJavaScriptビルドウォッチャーも起動します)。
このバンドラーがプロジェクトディレクトリ内のスタイルシートファイルの変更を検出するたびに、以下の1を2にバンドルします。
app/assets/stylesheets/application.[bundler].css
app/assets/builds/application.css
これで、<%= stylesheet_link_tag "application" %>
と記述する標準的なアセットパイプラインの手法を引き続き用いて、ビルド出力をレイアウト内で参照できるようになります。
アプリケーションをproduction環境にデプロイすると、assets:precompile
タスクにcss:build
タスクがアタッチされ(package.json
にあるすべてのパッケージ依存関係がyarnでインストールされるようにするため)、続いてyarn build:css
を実行してすべてのエントリポイントをdevelopment環境のときと同様に処理します。アセットパイプラインはこの出力を拾い上げてダイジェスト化し、他のアセットパイプラインファイルと同様にpublic/assetsディレクトリにコピーします。
これと同じことが、テストでバンドラーがtest:prepare
にアタッチするときにも行われ、テスト開始前にスタイルシートが確実にバンドルされるようになります。テストフレームワークがtest:prepare
Rake タスクを呼び出さない場合、テストフレームワークがテスト開始前に css:build
を実行してスタイルシートがバンドルされるようにしてください。セットアップでjsbundling-rails(つまりesbuildとtailwind)を利用している場合は、javascript:build
も実行するようにしておく必要があります。
概要は以上です。
バンドラーのオプションは、package.json
ファイル内のbuild:css
スクリプトで設定することも、インストーラが生成するファイルで設定することもできます(Tailwindの場合はtailwind.config.js
、PostCSSの場合はpostcss.config.js
)。
インストール
システムにnodeとyarnをインストールしておく必要があります。また、npx 7.1.0以降も必要です。
以下を実行します。
./bin/bundle add cssbundling-rails
を実行./bin/rails css:install:[tailwind|bootstrap|bulma|postcss|sass]
を実行
Rails 7以降は、新規アプリケーション作成時にcssbundling-rails
でbootstrap
、bulma
、またはpostcss
をバンドラーとして事前設定する場合は、rails new myapp --css [bootstrap|bulma|postcss]
のように指定できます。
FAQ
🔗 Q1: tailwindcss-railsやdartsass-railsと比べてどう違いますか?
JavaScriptの処理で既にNodeに依存している場合は、このcssbundling-rails gemを使うことになります。しかしRails 7以降でデフォルトとなったimportmapを使っている場合は、Tailwind CSSやDart Sassをスタンドアロンで利用できるtailwindcss-railsやdartsass-railsを使えば、Nodeと一切関わらずに済むようになります。これらはNodeよりもシンプルで可動部品も少なく、それでいてすべての機能を備えています。
Rails 7以降は、新規アプリケーション作成時にtailwindcss-rails
またはdartsass-rails
を事前設定する場合は、rails new myapp --css [tailwind|sass]
のように指定できます。
🔗 Q2: TailwindでCSSファイルを相対インポートする方法は?
Tailwindのapplication.jsファイル内で @import
ステートメントを使いたいのであれば、Tailwindでpostcss
を使う設定にしてからpostcss-import
プラグインを使う必要があります。
しかし、多数のCSSファイルをバンドルして1個の巨大ファイルにする代わりに、それらのCSSファイルを単に直接参照する方法も検討すべきです。application.html.erbファイル内の stylesheet_link_tag
を以下ののように展開すれば、他のCSSファイルを参照できます。
<%= stylesheet_link_tag "application", "other", "styles", "data-turbo-track": "reload" %>
🔗 Q3: 既存プロジェクトのSassC::SyntaxError
例外を回避するには?
一部のCSSパッケージでは、以前のバージョンのRailsで用いられていたデフォルトのSassC Rails統合でサポートされていない新しいCSS機能が使われていることがあります。このような非互換性に遭遇すると、assets:precompile
を実行したときにSassC::SyntaxError
のようなエラーが発生する可能性があります。
これを修正するには、bundle remove sass-rails
(sassc-railsを使っている場合はbundle remove sassc-rails
)を実行します。
🔗 Q4: production環境で application.css not in asset pipeline
が発生しました
よくある原因は、ビルドコンポーネントで使われる出力ディレクトリがそのリポジトリに存在していないというものです。app/assets/builds
ディレクトリを利用可能にしておく必要があります。このディレクトリ内に.gitkeep
ファイルを追加しておけば、production環境で利用できるようになります。
🔗 Q5: ActionView::Template::Error: Error: Function rgb is missing argument $green
エラーを回避する方法を教えてください
このエラーは、Gemfile.lockにレガシーなsassc-rails
が含まれている場合に発生する可能性があります。これは、プロジェクトを段階的に移行する途中で必要となるか、プロジェクトで直接制御できない間接的な依存関係である可能性があります。
この場合は以下のように、このgemが既に実行しているバンドルにSprocketsがCSSを追加バンドルしないようにします。この対応は、production環境だけでなくすべての環境で行うようにしてください。そうしないとテストスイートが失敗する可能性があります。
# config/initializers/assets.rb
Rails.application.config.assets.css_compressor = nil
🔗 Q6: 更新されたCSSファイルがRailsで使われません
注意: ローカルでプリコンパイルしたファイルが存在すると、動的に生成されたファイルよりも優先して配信されます。解決するには、以下を実行してください。
rails assets:clobber
🔗 node_modules
にあるサードパーティのスタイルシートを自分のバンドルに含める方法を教えてください。
以下のように@import
ステートメントで指定のスタイルシートへのパスを記述するときに、node_modules/
とファイル拡張子を書かないようにします。
/* 使いたいファイルの場所: node_modules/select2/dist/css/select2.css */
@import "select2/dist/css/select2";
ライセンス
CSS Bundling for Rails is released under the MIT License.
概要
MITライセンスに基づいて翻訳・公開いたします。