Dart SassのレガシーJS API非推奨警告の解消方法

問題の説明

Viteを使用した開発環境で、以下の警告メッセージが表示される問題が発生します：

Deprecation [legacy-js-api]: The legacy JS API is deprecated and will be removed in Dart Sass 2.0.0.

この警告は、プロジェクト内でレガシーなSass JS APIが使用されていることを示しています。特に、Create React App (CRA) からViteに移行したプロジェクトで頻繁に発生します。Dart Sass 2.0.0以降ではこのAPIが完全に削除されるため、開発中やビルド時に表示される警告を解消することが重要です。

発生条件

• Viteを使用した環境
• Sassバージョン1.79.1以上
• レガシーAPI（sass.render()など）を用いたSass処理

注意点

この警告を放置すると、将来のDart Sassアップデートでプロジェクトのビルドが失敗する可能性があります。早期に対応することが推奨されます。

根本的な解決方法

Vite設定の変更（推奨解決策）

Viteの設定ファイル（vite.config.jsまたはvite.config.ts）を更新し、Sass APIをモダンな実装に明示的に切り替えます：

import { defineConfig } from 'vite';

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        // モダンAPIを明示的に指定
        api: 'modern-compiler', // 'modern'でも可
      }
    }
  }
});

各オプションの違い：

• modern-compiler: 最新のコンパイラAPIを使用（最適なパフォーマンス）
• modern: モダンAPIを互換モードで使用
• legacy: 従来のAPI（デフォルト・非推奨）

設定ファイルの場所

• vite.config.js (JavaScript)
• vite.config.ts (TypeScript)
• vite.config.dev.mjs/vite.config.prod.mjs (環境別設定)

SCSSファイルの移行

レガシーな@importをモダンな@useに置き換えることで、完全な互換性を確保します：

# sass-migratorをインストール
npm install -g sass-migrator

# プロジェクト内の全SCSSファイルを移行
find . -type f -name "*.scss" -exec sass-migrator module --migrate-deps {} +

移行前後のコード比較：

@import 'variables'; // レガシーなインポート

@use 'variables' as *; // モダンなインポート

グローバル変数の設定

プロジェクト全体で共有変数を使用する場合、Vite設定にエイリアスを追加します：

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        api: 'modern-compiler',
        additionalData: `@use "@/styles/global" as *;` // グローバル変数
      }
    }
  },
  resolve: {
    alias: {
      '@': '/src', // エイリアスの定義
    }
  }
});

警告を非表示にする方法（一時的対策）

根本的な解決が難しい場合、一時的に警告を非表示にする方法もあります：

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        silenceDeprecations: ["legacy-js-api"] // 警告を消去
      }
    }
  }
})

注意

これは警告を隠すだけで根本解決ではないため、推奨されない一時的な対策です。APIの移行が必要な状況は解決されません。

共通ライブラリの対応

Quasarフレームワークの場合

QuasarのViteプラグインを使用している場合、最適化されたCSSファイルを直接インポートします：

// 非推奨:
// import 'quasar/src/css/index.sass'

// 推奨:
import 'quasar/dist/quasar.css' // プリコンパイル版

トラブルシューティング

未解決の警告が残る場合

1. 依存パッケージの検査:

   npm list sass # Sassバージョンを確認

2. Node.jsバージョンの変更（最終手段）:

   nvm install 18.18.2 # 互換性の高いバージョン
   nvm use 18.18.2

3. 関連モジュールの更新:

   npm update sass vite --save-dev

最適化のポイント

• @useによるモジュール設計でスタイルのスコープを明確化
• コンパイラレベルの警告はCI環境のエラー閾値に含める

根本原因の技術的背景

レガシーAPIの問題点：

1. sass.render()は非同期処理に非対応
2. コンパイラ最適化の制限
3. モジュールシステム（@use）との非互換性

レガシーAPIからモダンAPIへの移行プロセス

移行のメリット：

• コンパイル速度の向上（約40%高速化）
• メモリ使用量の削減
• CSSモジュールとの統合強化
• 将来のSass機能への対応

関連リソース

• 公式移行ガイド
• Vite CSSプリプロセッサ設定
• Sassモジュールシステム解説