sass-migratorを活用して、node-sassをdart-sassへらくらく変換!!
現在、Sassは node-sass から dart-sass への移行が推奨されています。@import
が非推奨になり、 @use
や @forward
といった新しいモジュールシステムを使用することが推奨されるようになり、今まで運用していた Sass のコードを書き換えなければいけないという方も多いのではないでしょうか? 今回は、node-sass を dart-sass へ書き換えるときに便利な sass-migrator
というツールを紹介してみたいと思います。
sass-migrator とは
sass-migrator とは node-sass などの古い記述で書かれた .scss
ファイルを新しいバージョン(dart-sass)の記述に自動的に置換してくれるコマンドラインツールになります。
使い方
sass-migrator を実行するときは、どの記述の移行を行うかどうかと、どの .scss
ファイルに対して実行するかを、sass-migrator を実行するコマンドの引数に渡してあげる必要があります。構文は以下になります。
$ sass-migrator <migration> <entrypoint.scss...>
通常、sass-migrator はエントリポイントとして渡された .scss
ファイルのみを対象ファイルとして実行しますが、 --migrate-deps
オプションを渡すことで、sass-migrator は @use
、 @forward
、 @import
などのモジュールシステムを使用して読み込まれているファイルまで自動的に新しい記述に変換してくれます。また、実際にファイルに変更は加えず、テスト的に実行したいという場合には --dry-run --verbose
オプションを渡してあげることで、実際のファイルの変更は行わず、ターミナルに変更差分を表示させることができます。
以下は実際に sass-migrator を実行する前の .scss
ファイルと実行後の .scss
ファイルになります。(公式から引用)
// 実行前 $body-bg: #000; $body-color: #111; @import "bootstrap"; @include media-breakpoint-up(sm) { .navbar { display: block; } }
$ sass-migrator --migrate-deps module style.scss
// 実行後 @use "bootstrap" with ( $body-bg: #000, $body-color: #111 ); @include bootstrap.media-breakpoint-up(sm) { .navbar { display: block; } }
インストール方法
sass-migrator は npm からインストールできます。
$ npm i -D sass-migrator
オプション
sass-migrator にはいくつかオプションがありますので紹介します。
--migrate-deps
--migrate-deps
オプションを指定することで、コマンドで引数に指定しているファイルだけではなく、@use
や @forward
、@import
を使用して読み込まれているファイルも変換の対象として実行することができます。省略形は -d
です。
ただ、sass-migrator は @use
や @forward
を使用して読み込まれている場合、すでに新しいモジュールシステムの記述に移行していると仮定するため、たとえ、--migrate-deps
オプションが渡された場合でも、それらの移行は行われないそうです。
--dry-run
--dry-run
オプションを指定することで変更をディスクに保存しないように sass-migrator に支持することができます。つまり、このオプションを指定すると、実際にファイルの変更は行われません。代わりに変更されるファイルがターミナルにリスト表示されます。 --verbose
と一緒に利用することで変更されるファイルの変更内容も表示することができます。省略形は -n
です。
$ sass-migrator module --dry-run --migrate-deps style.scss Dry run. Logging migrated files instead of overwriting... style.scss _theme.scss _fonts.scss _grid.scss
--verbose
--verbose
オプションを指定することで、sass-migratorは追加情報をコンソールに出力します。sass-migrator を実行したときに、デフォルトでは変更があったファイル名を表示させますが、 --dry-run
と一緒に使用した場合は変更があったファイルの変更があった部分をを表示します。省略形は -v
です。
$ sass-migrator module --verbose --dry-run style.scss Dry run. Logging migrated files instead of overwriting... <==> style.scss @use "bootstrap" with ( $body-bg: #000, $body-color: #111 ); @include bootstrap.media-breakpoint-up(sm) { .navbar { display: block; } } $ sass-migrator module --verbose style.scss Migrating style.scss
Migrations
sass-migrator を実行するときにはどの記述を変更するかどうかという指定をする必要があります。それが
division
sass-migrator division styles.scss
のように division
を指定することで .scss
ファイル内の /
の記述を使用している除算を Built-in Modules である math.div
という記述に書き換えます。
--pessimistic
デフォルトでは、除算になるかどうかわからない場合でも、/
で記述された除算を math.div
に変換します。そのため、 math.div
の引数の1つが数値でない場合が発生する可能性があります。その場合、警告がコンソールに表示されます。
上記の挙動を避けたい場合に --pressimistic
オプションを指定することで、確実に確実に除算を行っていることがわかっている /
の指定のみを math.div
に変換します。これにより、不要な math.div
への変換を防ぐことができますが、静的に除算を行っているかどうかが判断できない場合には math.div
への移行が行われない可能性があるため注意が必要です。
module
sass-migrator module styles.scss
のように module
を指定することで @import
の記述で行われているモジュールの読み込みを @use
に書き換えることができます。単純に @import
を @use
に置換するだけではなく、sass-migratorを実行する前と実行後のファイルで同じ挙動になるよう以下の処理をしています。
- 他のモジュールのメンバー(variables, mixins, functions)の使用に名前空間を追加します。
- モジュールを import することなく使用していた
.scss
ファイルに@use
でそのファイル内で使用しているモジュールを読み込む記述を追加します。 - 他のファイルで使用されているメンバーの
-
や_
といったプレフィックスを自動で削除します。 - 入れ子になった import を
meta.load-css()
という記述に書き換えます。
また、モジュールシステムの変換はメンバー定義とメンバー名の両方を変更する必要がある場合があるため、-migrate-deps
オプションを指定して実行するか、パッケージまたはアプリケーションのすべてのスタイルシートを確実に渡すことが重要です。
--remove-prefix
module
を指定した場合は --remove-prefix
オプションを指定することで、全ての 変数、Mixin、関数名 から任意のプレフィックスを削除します。任意のプレフィックスが付与されていない変数、Mixin、関数名は変更されません。
@import
を使用して外部モジュールを読み込んでいた場合は、名前空間の衝突を避けるために変数、Mixin、関数名に特有のプレフィックスを付けて運用するというハックがありました。そういった運用は @use
と @forward
の登場によって必要がなくなりました。そのため、--remove-prefix
オプションはそれらの古いプレフィックスを削除するときに便利です。
$ cat style.scss @import "theme"; @mixin app-inverted { color: $app-bg-color; background-color: $app-color; } $ sass-migrator --migrate-deps module --remove-prefix=app- style.scss $ cat style.scss @import "theme"; @mixin inverted { color: theme.$bg-color; background-color: theme.$color; }
また、--remove-prefix
のオプションは複数渡すことができる他、カンマで区切ることで複数のプレフィックスを指定することもできます。複数のプレフィックスにマッチした場合は、最長一致のプレフィックスを削除します。
--forward
module
を指定した場合に、--forward
を指定することで、@forward
を使用して転送するモジュールを指定することができます。--forward=値
のように指定することができます。値は以下の値を設定できます。
none
(初期値)どのモジュールも@forward
を使用して転送しない設定です。all
実行前の.scss
ファイルで-
または_
で始まるメンバーを除いて全てのメンバーを@forward
を使用して書き換えます。prefixed
--remove-prefix
オプションに渡されたプレフィックスで始まるメンバーのみを転送します。このオプションは、--remove-prefix
オプションと組み合わせてのみ使用できます。
$ cat _index.scss @import "theme"; @import "typography"; @import "components"; $ sass-migrator --migrate-deps module --forward=all style.scss $ cat _index.scss @forward "theme"; @forward "typography"; @forward "components";
よく使用しそうなオプションは以上でしょうか?公式サイトには、他にもオプションがありますので気になる方は、公式サイトのほうを見ていただけると幸いです。
まとめ
dart-sass への移行を簡単にするツール sass-migrator について紹介させていただきました。もうちょっと自分なりにまとめた内容をブログに書きたかったのですが、なんだか公式サイトの英語を翻訳しただけみたいになってしまいました。この記事をみて、そういえばdart-sassへの移行をしていなかった!ということを思い出した方は、よかったらこの記事を見ながら sass-migrator で dart-sass への移行を済ませてしまってください。!!