Nuxtで Deprecation Warning: The legacy JS API is deprecated が発生したら

おつかれさまです。オウンドメディア担当の水谷です。
自チームのアプリの定期メンテナンス（ライブラリアップデート）をしていたところ掲題の警告が出るようになったのでその対応の備忘録を残します。

前提

• Nuxt 3.13.2
• Sass 1.77.8 → 1.79.3

Deprecation Warning: The legacy JS API is deprecated とは

https://sass-lang.com/documentation/breaking-changes/legacy-js-api/

Sassをコンパイルするエンドポイントとして

• 元々はNode SassベースのAPIが存在した（legacy API）
• 1.45.0から新しいAPIが誕生（new, modern API）
• legacy APIは2.0.0で廃止予定
• 1.79.0からlegacy APIを使っている場合に警告を出すようになった

https://vitejs.dev/config/shared-options#css-preprocessoroptions

• viteではdefaultはapi: "legacy"（legacy APIを使うようになっている）

対応方法1: いったん警告を抑制する

後述するハマりポイントなどの事情があってすぐにAPIを変更できない場合は警告を抑制することができます。
nuxt configで設定するなら下の位置にsilenceDeprecationsを設定できます。

nuxt.config.ts

export default defineNuxtConfig({
    vite: {
        css: {
            preprocessorOptions: {
                scss: {
                    // TODO: ハマりポイント解消までの暫定処置
                    silenceDeprecations: ["legacy-js-api"]
                }
            }
        }
    }
})

対応方法2: modern APIを使うようにする（オススメ！）

viteではapiに推奨値である"modern-compiler"に変更すればmodern APIに切り替わります。
nuxt configなら下記の位置にapiを設定できます。

nuxt.config.ts

export default defineNuxtConfig({
    vite: {
        css: {
            preprocessorOptions: {
                scss: {
                    // NOTE: modern APIを使う
                    api: "modern-compiler"
                }
            }
        }
    }
})

ハマりポイント: 外部ライブラリのcssが読み込めなくなる

modern APIに切り替えたところ、アプリ内のscssから外部ライブラリのcssを読み込めなくなる事象が発生しました😱

 ERROR  Pre-transform error: [sass] Can't find stylesheet to import.       18:59:46
  ╷
7 │ @use "node_modules/@lv-levtech/volt-vue/dist/style";
  │ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  ╵
  src/assets/scss/common.scss 7:1  root stylesheet

これはパスの指定方法を変更して<パッケージ名>/<export名>という形式にすることで解消できます。

common.scss

- @use "node_modules/@lv-levtech/volt-vue/dist/style";
+ @use "@lv-levtech/volt-vue/style.css";

※上の例はライブラリ側のpackage.jsonで./dist/style.cssが./style.cssとしてexports宣言されているため階層が変わっています。

ライブラリ側のpackage.json

{
    "exports": {
        "./style.css": "./dist/style.css"
    }
}

ライブラリ側でcssがexports宣言されていない場合はアプリ側でimport（use）できません
（ここが実際にハマったポイント）

自分がハマったライブラリは幸いにも社内ライブラリだったのですぐに修正依頼をかけられました。
OSSの場合はIssueを立ててアップデートを待つことになると思います。（自分でPRを立てちゃってもいいかも！？）