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 を実行するときにはどの記述を変更するかどうかという指定をする必要があります。それが です。大きく分けて2つあり、それに付随するオプションがいくつかありますので紹介します。

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 への移行を済ませてしまってください。！！