Angular Material 18 define-paletteエラー

問題

Angular Materialをバージョン18にアップグレードした後、ng serveまたはビルドプロセスを実行すると、以下のエラーが発生します：

X [ERROR] Undefined function.
   ╷
14 │ $myapp-theme-primary: mat.define-palette(mat.$indigo-palette, A400, A100, A700);
   │                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   ╵
  src\styles.scss 14:23  root stylesheet [plugin angular-sass]

    angular:styles/global:styles:2:8:
      2 │ @import 'src/styles.scss';
        ╵         ~~~~~~~~~~~~~~~~~

具体的な状況:

• ng update @angular/materialでアップグレード後に発生
• 以前のAngular Material v17では動作していたstyles.scssファイルがエラーを引き起こす
• mat.define-palette()関数が存在しないことが起因

WARNING

このエラーはAngular Material 18で導入された重大な変更(Breaking Change) が原因です。自動移行プロセスで全ての変更が適用されない場合があります。

原因の詳細

Angular Material 18では、Material DesignのM3(Material Design 3)システムがデフォルトとなりました。これに伴い：

• M2(Material Design 2)の関数は非推奨に
• M3系の新しいAPIの追加
• define-palette()などの関数名がm2-プレフィックス付きに変更
• パレット変数名もm2-プレフィックス付きに更新

元のコードで使用していた関数や変数は、新しい命名規則では利用できなくなりました。

解決方法

styles.scssの関数名と変数名を更新します。以下の手順で修正してください：

@use '@angular/material' as mat;
@include mat.core();

// 関数と変数に 'm2-' プレフィックスを追加
$myapp-theme-primary: mat.m2-define-palette(mat.$m2-indigo-palette, A400, A100, A700);
$myapp-theme-accent: mat.m2-define-palette(mat.$m2-indigo-palette);
$myapp-theme-warn: mat.m2-define-palette(mat.$m2-red-palette);

$myapp-theme: mat.m2-define-light-theme((
  color: (
    primary: $myapp-theme-primary,
    accent: $myapp-theme-accent,
    warn: $myapp-theme-warn,
  )
));

@include mat.all-component-themes($myapp-theme);

以下に変更箇所の詳細を示します：

<CodeGroup> <CodeGroupItem title="変更前" active>

// 古い関数と変数（v17以前）
$myapp-theme-primary: mat.define-palette(mat.$indigo-palette, A400, A100, A700);
$myapp-theme-accent: mat.define-palette(mat.$indigo-palette);
$myapp-theme-warn: mat.define-palette(mat.$red-palette);
$myapp-theme: mat.define-light-theme(...);

</CodeGroupItem> <CodeGroupItem title="変更後">

// 新しい関数と変数（v18以降）
$myapp-theme-primary: mat.m2-define-palette(mat.$m2-indigo-palette, A400, A100, A700);
$myapp-theme-accent: mat.m2-define-palette(mat.$m2-indigo-palette);
$myapp-theme-warn: mat.m2-define-palette(mat.$m2-red-palette);
$myapp-theme: mat.m2-define-light-theme(...);

</CodeGroupItem> </CodeGroup>

重要な変更点

1. 関数名の更新:

   • mat.define-palette() → mat.m2-define-palette()
   • mat.define-light-theme() → mat.m2-define-light-theme()

2. パレット変数の更新:

   • mat.$indigo-palette → mat.$m2-indigo-palette
   • mat.$red-palette → mat.$m2-red-palette

3. M2関連の関数と変数にはすべてm2-プレフィックスが必要:

   • Material 18ではM3がデフォルトとなりますが、従来のM2を使用したい場合はこのプレフィックスが必須です

TIP

@include mat.all-component-themes($myapp-theme);は変更不要です。テーマ適用の関数には変更がありません。

補足情報

• Angular Material公式リリースノート:
  Angular Material 18.0.0リリースノートの「Breaking Changes」セクションに詳細があります

• Material Designのバージョン選択:

  • M3(Material Design 3)に移行する場合は、代わりに新しい関数define-palette() (プレフィックスなし) を使用します
  • M2からの移行期間はm2-プレフィックス付き関数で従来の動作を維持できます

• 移行に備えて:

  # 完全な依存関係の更新を確実に実行
  npx ng update @angular/core @angular/cli
  npx ng update @angular/material

再発防止策

1. アップグレード時に公式ドキュメントを参照
2. ng update実行後にリリースノートで重大な変更を確認
3. 複数バージョンのプロジェクトではm2-やm3-プレフィックスの目的を理解：
   • m2-: Material Design 2（レガシーサポート）
   • m3-: Material Design 3（最新デフォルト）

これでmat.define-palette関連のエラーが解消し、プロジェクトが正常にビルドできるようになります。