はじめに

この記事は、sass-loader v16.0.0で導入されたSass JavaScript modern optionsについての解説と、その移行方法について共有するためのものです。

対象とする読者

webpackを利用している
sass-loaderを利用している
sass-loader v14以前を利用している
sass-loader v16.0.0への移行を検討している

対象とする環境

node.js v20.16.0
webpack v5.83.0
sass-loader v16.0.0

sass-loader v16.0.0での変更点

2024/07/26にリリースされたsass-loader v16.0.0では、Sass JavaScript modern optionsがデフォルトで有効になりました。
v14まで利用されていたオプションは、Legacy optionsと呼ばれるようになります。
Legacy optionsは引き続き利用可能ですが、将来的には廃止される予定です。

sass-loaderにおけるdart-sassのoptionsとは？

sass-loaderは、webpackでSassをコンパイルするためのローダーで、内部的にdart-sassなどのSassコンパイラを利用しています。
sass-loaderはwebpack.config.jsからdart-sassを設定するためのオプションを提供しています。

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          "style-loader",
          "css-loader",
          {
            loader: "sass-loader",
            options: { // ここがdart-sassに渡されるオプション
              ...
            },
          },
        ],
      },
    ],
  },
};

dart-sassのモダンオプションとレガシーオプション

dart-sassは現在v2へのアップデートが進められています。レンダリング関数はv1のrender()からv2のcompile()に差し替えられます。

modern options
legacy options

modern optionsはcompile()関数の引数、legacy optionsはrender()関数の引数に対応しています。

移行方法

v14までのsass-loaderを利用しているユーザーが、v16に移行する際には、以下の2つの方法があります。

レガシーオプションを有効にする

sass-loaderのオプションにapi: "legacy"を指定することで、レガシーオプションを有効化します。

{
    loader: "sass-loader",
    options: {
        api: "legacy", // レガシーオプションを有効にする
    },
},

レガシーオプションはdart-sass v2で廃止される予定です。

モダンオプションに切り替える

レガシーオプションとモダンオプションは直接対応する項目がありません。それぞれの設定に合わせて移行方法を調査する必要があります。

一例としてincludePathsの移行方法を示します。

{
    loader: "sass-loader",
    options: {
        api: "legacy",
        includePaths: ["node_modules/bootstrap/dist/css"]
    }
}

includePathsはsassの@useインポートパスを省略するためのオプションです。上記の例ではbootstrapのインポートパスを指定しています。

モダンオプションにはincludePathsに直接対応する機能はありません。代替としてPackage Importerという新機能が提供されています。

npm i -D sass-embedded

まず最初にsass-embeddedをインストールします。このパッケージはsassをDart実装です。モダンオプションに対応しており、また動作速度が向上しています。

@use "pkg:<パッケージ名>"; //対象パッケージのpackage.jsonで、exportsフィールドが指定されている場合
@use "pkg:<パッケージ名>/build/bundle.css"; //exportsフィールドが指定されていなくても、パッケージ内のファイルを呼び出せる

sassファイル内で@use "pkg:<パッケージ名>"を呼び出せば、npmパッケージ内のスタイルファイルをインポートできます。
Package Importerはsass-loderとsass-embeddedの組み合わせではデフォルトで有効化されており、webpack.config.jsで設定は不要です。includePathsは削除します。

modern optionsへの移行について、現状ではマイグレーションガイドがありません。最新情報を確認したい場合はsassの公式Blogを参照してください。

以上、ありがとうございました。