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

dartsass-rails README(翻訳)

概要

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

なお、従来のsassc-railsで使われているlibsassは現在非推奨です。

dartsass-rails README(翻訳)

Sassは、CSSにコンパイルされるスタイルシート言語です。Sassでは「変数」「ネステッドルール」「ミックスイン」「関数」などさまざまな機能が利用でき、いずれの構文もCSSと完全に互換性があります。

このgemには、Dart版Sassのスタンドアロンの実行可能ファイルが同梱されています。これらの実行可能ファイルはプラットフォーム固有であり、macOS(Intel、Apple Silicon)、Linux(x86-64、AArch64)、Windows(x86-64)向けの実行可能ファイルが含まれます。

インストーラを実行すると、デフォルトのSass入力ファイルがapp/assets/stylesheets/application.scssに作成されます。コンパイルしたいすべてのスタイルファイルは、このファイルで@useルールを用いてインポートする必要があります。rails dartsass:buildを実行すると、このSass入力ファイルがapp/assets/builds/application.css出力ファイルの生成に使われます。この出力CSSがアプリケーションに含められます。Sassの読み込みパスは自動的にapp/assets/stylesheetsに設定されます。

ビルドプロセスをビルドファイル以外の方法で設定する必要がある場合は、bundle exec dartsassを実行してプラットフォーム固有の実行可能ファイルにアクセスし、そこでビルドオプションを渡します。

アプリケーションの開発中に、Dart Sassをウォッチモードで実行して、変更内容を生成されたCSS出力ファイルに自動反映したい場合は、rails dartsass:watchを別プロセスで実行するか、./bin/devを実行します。後者はforemanを用いてDart SassのウォッチプロセスとdevelopmentモードのRailsサーバーを同時に起動します。

🔗 インストール

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

🔗 production向けビルド

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

🔗 ビルドを設定する

デフォルトではapp/assets/stylesheets/application.scssファイルのみがビルド対象となります。このスタイルシートのパスを変更したい場合、エントリポイントに追加したい場合、ビルドファイル名をカスタマイズしたい場合は、以下のようにRails.application.config.dartsass.builds設定にハッシュで指定します。

# config/initializers/dartsass.rb
Rails.application.config.dartsass.builds = {
  "app/index.sass"  => "app.css",
  "site.scss"       => "site.css"
}

ハッシュのキーは、app/assets/stylesheets/にあるSassファイルの相対パスです。ハッシュの値にはapp/assets/builds/に出力されるファイル名を指定します。

🔗 ビルドオプションを設定する

デフォルトのSassは--style=compressed --no-source-mapオプション付きで呼び出されます。これらのオプションを調整するには、以下のようにRails.application.config.dartsass.build_optionsを上書きします。

# config/initializers/dartsass.rb
Rails.application.config.dartsass.build_options << " --quiet-deps"

🔗 gemのアセットをインポートする

dartsass:buildには、アプリケーションのアセットのパスがSassの読み込みパスとしてインクルードされます。gemのアセットがRailsアプリケーションから見えるようになっていれば、追加設定なしで利用できます。

🔗 sass-railsから移行する

sass-rails(またはsassc-rails)からdartsass-railsに移行したい場合は、以下の手順に沿って作業します。

  1. ./bin/bundle remove sass-railsを実行してGemfileからsass-rails gemを削除する。

  2. 上述のインストール手順に沿ってdartsass-railsをインストールする。

  3. app/assets/config/manifest.js(Sprocketsのマニフェストファイル)からSassファイルへの参照をすべて削除する。

  4. ブラウザを操作するテストをCIパイプラインで実行する前に、以下を実行してSassファイルがビルドされることを確認する。

bundle exec rails dartsass:build

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

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

🔗 LoadError: cannot load such file -- sassc

上のエラーは、SprocketsがSassファイルのビルドを試みたときにsass-railsまたはsassc-railsがインストールされていないことが原因です。これはDart SassがSassファイルをビルドするので予定通りの動作であり、解決するにはSprocketsがSassファイルをビルドしないようにします。

このエラーの発生原因は3つあります。

1. SassファイルがSprocketsのマニフェストファイルで参照されている

Sprocketsのマニフェストファイル(app/assets/config/manifest.js)でSassファイルが参照されていると、SprocketsがそのSassファイルをビルドしようとして失敗します。

  • 解決方法

Sprocketsのマニフェストファイル内にあるSassファイルへの参照をすべて削除します。これでSassファイルがDart Sassによって扱われるようになります。application.scss以外のSassファイルもある場合は、それらのファイルもDart Sassでコンパイルされるようにします(上述のビルドを設定するを参照)。

2. ローカル実行している場合

Sprocketsのマニフェストファイル内にあるSassファイルへの参照をすべて削除したにもかかわらず、Railsサーバーをローカルで実行するとこのエラーが発生する場合は、Dart Sassプロセスが動いていない可能性があります。

  • 解決方法

Dart Sassプロセスを実行するためにRailsサーバーを./bin/devで起動します。

3. CIパイプラインで実行する場合

Sprocketsのマニフェストファイル内にあるSassファイルへの参照をすべて削除したにもかかわらず、CIのブラウザ連動テストでこのエラーが発生する場合、Sassファイルがビルドされていない可能性があります。

  • 解決方法

Sassファイルをビルドするbundle exec rails dartsass:buildコマンドを実行するステップをCIパイプラインに追加します。

バージョン

Dart Sass 1.49.0

ライセンス

Dart Sass for Rails is released under the MIT License.
Sass is released under the MIT License.

関連記事

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

cssbundling-rails README(翻訳)

Propshaft gem README(翻訳)


CONTACT

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