破壊的変更: レガシー JS API

使用法の移行使用法の移行のパーマリンク

エントリポイントエントリポイントのパーマリンク

レガシーJS APIには、Sassをコンパイルするための2つのエントリポイントがありました。renderとrenderSyncです。これらは、file（ファイルをコンパイルする場合）またはdata（文字列をコンパイルする場合）を含むオプションオブジェクトを受け取りました。最新のAPIには4つのエントリポイントがあります。ファイルコンパイル用のcompileとcompileAsync、文字列コンパイル用のcompileStringとcompileStringAsyncです。これらの関数は、最初の引数としてパスまたはソース文字列を受け取り、次に他のすべてのオプションのオブジェクトを2番目の引数として受け取ります。コールバックを使用したrenderとは異なり、compileAsyncとcompileStringAsyncは代わりにpromiseを返します。

詳細については、使用法のドキュメントを参照してください。

インポーターインポーターのパーマリンク

レガシーAPIのインポーターは、依存関係ルールURLと、含まれるスタイルシートのURL（および非同期インポーター用のdoneコールバック）を受け取り、ディスク上のfileパス、またはロードされるスタイルシートのcontentsを含むオブジェクトを返す単一の関数で構成されていました。

最新のAPIのImporterは、代わりに2つのメソッドを含んでいます。canonicalizeはルールURLを受け取り、そのURLの正規の形式を返します。loadは正規のURLを受け取り、ロードされたスタイルシートのコンテンツを含むオブジェクトを返します。この分割により、同じモジュールが1回だけロードされ、相対URLが一貫して機能することが保証されます。非同期インポーターでは、これらの両方のメソッドがpromiseを返します。

また、ディスク上の既存のファイルへのすべてのロードをリダイレクトする特別なFileImporterもあり、contentsの代わりにfileを返したレガシーインポーターから移行するときに使用する必要があります。

カスタム関数カスタム関数のパーマリンク

レガシーJS APIでは、カスタム関数はSass引数ごとに個別のJS引数を取り、非同期カスタム関数の場合は追加のdoneコールバックを取りました。最新のAPIでは、カスタム関数は代わりにすべてのSass引数のリストを含む単一のJS引数を取り、非同期カスタム関数はpromiseを返します。

最新のAPIは、すべてのSass値の型、型アサーション、および簡単なマップとリストのルックアップをサポートする、はるかに堅牢なValueクラスも使用します。

バンドラーバンドラーのパーマリンク

Sass APIを直接使用するのではなく、バンドラーまたは他のツールを使用している場合は、そのツールに渡す構成を変更して、最新の APIを使用するように指示する必要がある場合があります。

Webpackはデフォルトで最新のAPIを既に使用しているはずですが、警告が表示される場合は、apiを"modern"または"modern-compiler"に設定します。詳細については、Webpackのドキュメントを参照してください。

ViteはまだレガシーAPIをデフォルトで使用していますが、apiを"modern"または"modern-compiler"に設定することで同様に切り替えることができます。詳細については、Viteのドキュメントを参照してください。

他のツールについては、最新のSass APIのサポートに関する情報について、ドキュメントまたはIssueトラッカーを確認してください。

警告の抑制警告の抑制のパーマリンク

レガシーJS APIは、Dart Sass 1.45.0で最新のAPIのリリースとともに非推奨としてマークされましたが、Dart Sass 1.79.0から使用に関する警告を出し始めました。まだ最新のAPIに移行できないが、今のところ警告を抑制したい場合は、silenceDeprecationsオプションでlegacy-js-apiを渡すことができます。

const sass = require('sass');

const result = sass.renderSync({
  silenceDeprecations: ['legacy-js-api'],
  ...
});

これにより、今のところ警告が抑制されますが、レガシーAPIはDart Sass 2.0.0で完全に削除されるため、できるだけ早く移行を計画する必要があります。