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

cssbundling-rails README(翻訳)

概要

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

cssbundling-rails README(翻訳)

cssbundling-rails gemは、Tailwind CSSBootstrapBulmaPostCSS、または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にバンドルします。

  1. app/assets/stylesheets/application.[bundler].css
  2. 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にアタッチするときにも行われ、テスト開始前にスタイルシートが確実にバンドルされるようになります。ただし、現時点ではRailsのtest:*タスク(test:alltest:controllersなど)のみが対象である点にご注意ください(rails testtest: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以降も必要です。

以下を実行します。

  1. ./bin/bundle add cssbundling-railsを実行
  2. ./bin/rails css:install:[tailwind|bootstrap|bulma|postcss|sass]を実行

Rails 7以降は、新規アプリケーション作成時に利用するバンドラーをrails new myapp --css [tailwind|bootstrap|bulma|postcss|sass]のように事前に指定できます。

FAQ

Q1: tailwindcss-railsやdartsass-railsと比べてどう違いますか?

JavaScriptの処理で既にNodeに依存している場合は、このcssbundling-rails gemを使うことになります。しかしRails 7以降でデフォルトとなったimportmapを使っている場合は、Tailwind CSSやDart Sassをスタンドアロンで利用できるtailwindcss-railsdartsass-railsを使えば、Nodeと一切関わらずに済むようになります。これらはNodeよりもシンプルで可動部品も少なく、それでいてすべての機能を備えています。

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環境で利用できるようになります。

ライセンス

CSS Bundling for Rails is released under the MIT License.

関連記事

Rails 7: importmap-rails + tailwindcss-railsでnode.jsが不要な理由

Rails 7: dartsass-rails gemはNode.jsなしで使える


CONTACT

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