라떼군 이야기
Angular Material 18 업데이트 후 mat.define-palette 'Undefined function' 에러 해결 방법
Problem
Angular 프로젝트를 버전 18로 업그레이드(ng update @angular/material)한 후, 애플리케이션을 컴파일하거나 실행할 때 SCSS 파일에서 에러가 발생하는 상황입니다.
구체적으로 styles.scss 파일에서 기존에 잘 사용하던 mat.define-palette 함수에 대해 다음과 같은 에러 메시지가 출력됩니다:
X [ERROR] Undefined function.
╷
14 │ $myapp-theme-primary: mat.define-palette(mat.$indigo-palette, ...);
│ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
이전 버전(v17)까지는 문제없이 작동하던 코드가 업데이트 직후 ‘함수를 찾을 수 없다’는 오류를 뱉어내며 빌드에 실패합니다.
Background
Angular Material 18 버전은 Material Design 3 (M3) 지원을 강화하면서 스타일링 API에 큰 변화가 있었습니다. 이 과정에서 기존 Material Design 2 (M2) 기반의 테마 시스템과 새로운 M3 시스템을 명확히 구분하기 위해 네이밍 규칙이 변경되었습니다.
기존에 사용하던 define-palette, define-light-theme 등의 함수와 $indigo-palette 같은 변수들은 이제 ‘레거시(Legacy)’ 또는 ‘M2’로 분류됩니다. 따라서 v18부터는 이러한 구형 API들이 기본 네임스페이스에서 제거되었거나 이름이 변경되었기 때문에, 자동 마이그레이션이 완벽하게 수행되지 않았다면 수동으로 코드를 수정해야 합니다.
Solution
이 문제를 해결하는 가장 간단한 방법은 기존 코드가 Material Design 2(M2) API를 명시적으로 사용하도록 함수와 변수 이름을 변경하는 것입니다. Angular Material 18에서는 M2 관련 기능에 m2- 접두사가 붙었습니다.
코드 수정 방법
styles.scss 파일에서 테마 정의 부분을 다음과 같이 수정하세요.
수정 전 (v17 이하):
@use '@angular/material' as mat;
@include mat.core();
// 기존 함수 및 변수 사용
$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((
color: (
primary: $myapp-theme-primary,
accent: $myapp-theme-accent,
warn: $myapp-theme-warn,
)
));
@include mat.all-component-themes($myapp-theme);
수정 후 (v18):
@use '@angular/material' as mat;
@include mat.core();
// 1. 팔레트 정의 함수: define-palette -> m2-define-palette 로 변경
// 2. 색상 팔레트 변수: $indigo-palette -> $m2-indigo-palette 로 변경
$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);
// 3. 테마 생성 함수: define-light-theme -> m2-define-light-theme 로 변경
$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);
주요 변경 사항 요약
mat.define-palette→mat.m2-define-palettemat.$[color]-palette→mat.$m2-[color]-palettemat.define-light-theme→mat.m2-define-light-thememat.define-dark-theme→mat.m2-define-dark-theme
이처럼 m2- 접두사를 붙여줌으로써 Angular Material에게 “나는 아직 Material Design 2 스타일을 사용하겠다"고 명시적으로 알리는 것입니다.
Deep Dive
Material Design 3 (M3)로의 전환 고려
위의 해결책은 기존 디자인(M2)을 유지하면서 에러를 수정하는 방법입니다. 하지만 Angular Material 팀은 점진적으로 Material Design 3(M3)로의 전환을 권장하고 있습니다.
만약 프로젝트의 디자인 시스템을 최신 트렌드에 맞게 업데이트할 계획이라면, m2- 접두사를 사용하는 대신 새로운 M3 테마 API인 mat.define-theme()를 사용하는 것을 고려해보세요. M3는 색상 팔레트 구조가 다르며(Primary, Secondary, Tertiary 등), 시스템 기반의 동적 색상을 더 잘 지원합니다.
자동 마이그레이션 실패 원인
일반적으로 ng update 명령어는 이러한 변경 사항을 자동으로 처리하려고 시도합니다. 하지만 SCSS 파일 구조가 복잡하거나, 변수를 재할당하여 사용하는 등 정적 분석이 어려운 패턴으로 코드가 작성되어 있다면 자동 변환이 누락될 수 있습니다. 메이저 업데이트 후에는 항상 스타일 파일을 수동으로 점검하는 것이 좋습니다.
Conclusion
Angular Material 18 업데이트 시 발생하는 Undefined function 에러는 M2와 M3 API 분리에 따른 네이밍 변경 때문입니다. 기존 디자인을 유지하려면 테마 관련 함수와 변수 앞에 m2-를 붙여주는 것으로 간단히 해결할 수 있습니다. 장기적으로는 Material Design 3로의 마이그레이션도 고려해보시기 바랍니다.