dartsass-rails README（翻訳）
Sassは、CSSにコンパイルされるスタイルシート言語です。Sassでは「変数」「ネステッドルール」「ミックスイン」「関数」などさまざまな機能が利用でき、いずれの構文もCSSと完全に互換性があります。
このgemには、Dart版Sassのスタンドアロンの実行可能ファイルが同梱されています。プラットフォーム固有のDart Sass実行ファイルはsass-embedded gemで配布されます。
インストーラを実行すると、デフォルトの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サーバーを同時に起動します。
🔗 インストール
./bin/bundle add dartsass-railsを実行./bin/rails dartsass:installを実行
追記（2023/09/14）
Rails 7.0では、rails new -c sassを指定するとdartsass-rails gemではなく、cssbundling-rails経由でsassがインストールされるのでご注意ください。
Rails 7.1からは-c sassでdartsass-rails gemがインストールされるようになる予定です。
参考: 週刊Railsウォッチ20230322 rails newの--css sassでdartsass-railsが使われるようになった
🔗 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/に出力されるファイル名を指定します。
If both the hash key and the hash value are directories instead of files, it configures a directory to directory compliation, which compiles all public Sass files whose filenames do not start with underscore (_).
ハッシュのキーと値が両方ともファイルではなくディレクトリの場合は、ディレクトリからディレクトリへのコンパイルが設定されます。この場合、ファイル名がアンダースコア_で始まらないすべてのpublicなSassファイルがコンパイルされます。
# config/initializers/dartsass.rb
Rails.application.config.dartsass.builds = {
"." => "."
}
🔗 ビルドオプションを設定する
デフォルトのSassは["--style=compressed", "--no-source-map"]オプション付きで呼び出されます。これらのオプションを調整するには、以下のようにRails.application.config.dartsass.build_optionsを上書きします。
# config/initializers/dartsass.rb
Rails.application.config.dartsass.build_options << "--no-charset" << "--quiet-deps"
🔗 gemのアセットをインポートする
dartsass:buildには、アプリケーションのアセットのパスがSassの読み込みパスとしてインクルードされます。gemのアセットがRailsアプリケーションから見えるようになっていれば、追加設定なしで利用できます。
🔗 sass-railsから移行する
sass-rails（またはsassc-rails）からdartsass-railsに移行したい場合は、以下の手順に沿って作業します。
./bin/bundle remove sass-railsを実行してGemfileからsass-rails gemを削除する。-
上述のインストール手順に沿ってdartsass-railsをインストールする。
-
app/assets/config/manifest.js（Sprocketsのマニフェストファイル）からSassファイルへの参照をすべて削除する。
-
ブラウザを操作するテストを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パイプラインに追加します。
バージョン
bundle exec dartsass --version
ライセンス
Dart Sass for Rails is released under the MIT License.
Sass is released under the MIT License.
概要
MITライセンスに基づいて翻訳・公開いたします。
なお、従来のsassc-railsで使われているlibsassは現在非推奨です。