sass-migratorを使ってLibSassからDartSassに移行する手順

少し前に重い腰をあげてようやくLibSass(node-sass)から移行したので、その時のメモを残します。

Sass の@import 廃止は2022年10月と発表されていましたが、DartSassの使用率が80％になるまで延期する旨が2022年7月に公式のGitHub にて記載されてました。そのため当初の予定よりも猶予はありますが、近い将来廃止が確定しているため、どこかのタイミングで切り替える必要があります。
※余談ですが私が移行したのは廃止日の問題ではなく、M1 Macbookの仕様の問題だったりします。M1 はLibSass が通らないので新規pjだとLibSass は使用できない / 既存pjであったとしてもnode_module をすべて消去して再度npm install をしてしまうとアウトなので注意。

結論からいうとMigrator のおかげで思っていたよりもスムーズに移行できたので、これから移行する方の参考になれば幸いです。Migrator さんありがとう…！

移行にはsass-migratorを使用

LibSass とDartSass は@import 廃止以外にも記述が違う点がいくつかあります。この記事では詳しく書きませんので、詳細を知りたい方は下記の記事を参照してみてください。

https://kojika17.com/2020/05/next-generation-sass-module-system.html

単純に@import を@use や@forward に置換すればいいわけではなく、だからといって手作業で全てを修正するのは非常に面倒です。そこで移行の前にsass-migratorという、LibSass等で書かれた古い.scssをDartSassの記法に自動で置換してくれるコマンドラインツールを使用します。

sass-migrator

使い方

まずはLibSassのアンインストールをしておきます。

$ npm remove node-sass

続いて、Migrator とDartSass のインストールします。

$ npm i -D sass sass-migrator

// sassが既にインストール済みの場合はmigiratorのみで
$ npm i -D sass-migrator

インストールが完了したら、以下のコマンドを実行します。

$ npx sass-migrator --migrate-deps module src/styles/style.scss

これで完了です。分かりやすいようにパスも書いていますが、これは私の環境が以下のようなディレクトリ構成をしているためなので、環境によって適宜変更していただければ。

---

develop/
├ src/
└ styles/
　└ 各種scssフォルダと.scssファイル
　└ style.scss (すべてのscssファイルを@import で集約している)
├ node_modules
└ package.json

---

オプション

こちらもドキュメントに書いてあるとおりですが補足として。

--migrate-dep

コマンドラインで直接指定したファイルだけではなく、@useルール、@forwardルール、@importルールを使って依存しているスタイルシートも変更します。この翻訳テキストだけ読んでるとイメージしづらいのですが、ドキュメントを確認すると納得します。

$ sass-migrator module --verbose style.scss
Migrating style.scss
$ sass-migrator module --verbose --migrate-deps style.scss
Migrating style.scss
Migrating _theme.scss
Migrating _fonts.scss
Migrating _grid.scss

@import記法だと、style.scss の中に全ての.scssファイルが@import で読み込まれてるケースがほとんどだと思うので、style.scssとだけ書いてくれたら中の@import で書かれている.scssも読むよってことです。
ただ、レアケースとは思うんですが、稀にstyle.scssに@import されていない.scssがあるかもしれないので、不安な場合はオプションの-–load-pathを用いて以下の実行コマンドにするとよさそうです。

$ npx sass-migrator --migrate-deps module src/styles/** --load-path ./src/styles/

--dry-run

このオプションをつけて実行するとファイル自体は変更されず、どのファイルに変更があるのか確認できます。通常は --verbose オプションと組み合わせて使用します。
私の場合は最初にテスト用ファイルを作ってたのでこちらは使用しなかったのですが、一度実行すると元に戻すのも面倒なので、実行前にまず確認してみたい場合こちらのオプションを書いてから実行しましょう。

sass-migrator実行後のターミナルエラー

何の問題もなくあっさり完了してくれたらいいのですが、いくつかターミナル上でエラーが出たので事例を紹介します。

数字のファイル名は使用できない

404.scssとか作ったばかりに。
エラーログに書いてあるとおりなんですが、命名を変更するか、どうしても命名を変更したくない場合は読み込み時に as節を使って書き換えてあげる必要があります。

@use 'pages/404' as notfound;

除算はsass:mathモジュールを用いる

Sassは四則演算が出来るので便利なのですが、どうやらDartSass(1.33.0以降)では除算(/)は非推奨となっているようで、このようなエラーが出ます。
/だと除算か区切りかどちらの意味なのか分かりづらいと公式で発表されていて、除算の代替にはビルドインモジュールのsass:mathの使用を推奨しています。

変更前の例

.example{
  width: (100% / 3);
}

変更後

@use "sass:math"; /* 行頭で必ず記述 */
 
.example{
  width: math.div(100%, 3);
}

sass:mathの使用には行頭に @use "sass:math"; の記述が必須なので忘れないように記述します。

私は手動で直しましたが、migrator を使用すれば一括で変更してくれるので、修正範囲が多い場合はmigrator を使用すると楽が出来そうです。

$ sass-migrator division **/*.scss

sass:mathモジュールには他にも関数があるので、演算を使う場合は一度覗いておくといいかも。
https://sass-lang.com/documentation/modules/math