Angular 18 업그레이드 시 '@angular/localize/init' Polyfill 경고 해결 방법
Problem
Angular 18로 프로젝트를 업그레이드한 후 ng serve 명령어를 실행할 때 터미널에 “Polyfill for ‘@angular/localize/init’ was added automatically"라는 경고 메시지가 나타나는 상황입니다. 기존 방식대로 polyfills.ts 파일에 import '@angular/localize/init'; 구문을 선언해 두었음에도 불구하고, 빌드 시스템이 이를 인식하지 못하고 향후 이 자동 추가 기능이 제거될 것이라고 경고합니다. 이는 애플리케이션의 실행 자체를 막지는 않지만, 지속적인 빌드 경고를 발생시켜 개발자 경험을 저하시키고 향후 버전에서의 호환성 문제를 암시합니다.
Background
Angular는 다국어 지원(i18n)을 위해 @angular/localize 패키지를 사용하며, 이를 활성화하려면 런타임에 특정 폴리필(Polyfill)이 필요합니다. 과거 버전에서는 polyfills.ts 파일을 별도로 생성하고 그 안에 필요한 폴리필을 import 구문으로 직접 선언하는 방식이 표준이었습니다. 하지만 Angular 최신 버전(특히 esbuild 기반 빌더가 도입된 이후)에서는 설정의 단순화와 빌드 성능 향상을 위해 angular.json에서 폴리필을 직접 문자열 배열 형태로 관리하도록 빌드 시스템이 변경되었습니다. 따라서 기존의 polyfills.ts 파일을 통한 임포트 방식은 레거시로 간주되며, Angular 18에서는 이를 명시적으로 angular.json으로 옮기도록 경고를 발생시켜 마이그레이션을 유도하는 것입니다.
Solution
이 문제는 프로젝트의 유형(일반 애플리케이션 vs 라이브러리)에 따라 해결 방법이 다릅니다. 상황에 맞는 방법을 선택하여 적용하세요.
1. 일반 Angular 애플리케이션의 경우
가장 일반적인 해결책으로, angular.json 파일의 설정을 변경하고 불필요해진 polyfills.ts 파일을 삭제합니다.
// angular.json
{
"projects": {
"MyClientApp": {
"architect": {
"build": {
"builder": "@angular-devkit/build-angular:browser-esbuild",
"options": {
"outputPath": "dist/MyClientApp",
"main": "src/main.ts",
"index": "src/index.html",
// 기존: ["src/polyfills.ts"]
// 변경: 패키지명을 직접 문자열로 추가합니다.
"polyfills": [
"@angular/localize/init"
],
"tsConfig": "tsconfig.app.json"
}
}
}
}
}
}
위와 같이 angular.json을 수정한 후, 기존의 src/polyfills.ts 파일이 오직 @angular/localize/init만을 임포트하고 있었다면 해당 파일을 안전하게 삭제할 수 있습니다. 이 방법은 설정 파일을 간소화하고 빌드 도구가 폴리필을 더 효율적으로 처리할 수 있게 해줍니다.
2. Angular 라이브러리 프로젝트의 경우
Angular 라이브러리 프로젝트는 angular.json에 polyfills 배열 옵션이 존재하지 않으므로 위의 방법을 사용할 수 없습니다. 대신 TypeScript의 참조 지시어(Triple-Slash Directives)를 활용해야 합니다.
먼저 라이브러리의 진입점 파일인 public-api.ts를 수정합니다.
// public-api.ts
// 기존의 import 구문을 삭제합니다.
// import '@angular/localize/init';
// 대신 TypeScript 컴파일러에게 해당 패키지의 타입을 참조하라고 지시합니다.
/// <reference types="@angular/localize" />
export * from './lib/my-library.service';
export * from './lib/my-library.component';
그 다음, 라이브러리의 tsconfig.json (또는 tsconfig.lib.json) 파일에 타입 참조를 추가합니다.
// tsconfig.json
{
"compilerOptions": {
// 컴파일 시 @angular/localize의 전역 타입을 포함하도록 설정합니다.
"types": ["@angular/localize"]
}
}
이 방법은 라이브러리 빌드 시 폴리필 경고를 제거하면서도, 라이브러리를 사용하는 측에서 올바른 다국어 타입을 추론할 수 있도록 보장합니다.
Deep Dive
Angular의 새로운 esbuild 기반 빌더(@angular-devkit/build-angular:browser-esbuild 또는 application 빌더)는 기존 Webpack 빌더보다 빌드 속도가 훨씬 빠르며, 설정 파일의 의존성을 줄이는 방향으로 발전하고 있습니다. polyfills.ts와 같은 별도의 진입점 파일을 제거하고 angular.json에 직접 문자열로 선언하면, 빌드 도구가 필요한 폴리필만 더 효율적으로 번들링하고 트리 쉐이킹(Tree Shaking)을 최적화할 수 있습니다. 프로덕션 환경으로 배포하기 전, 사용 중인 서드파티 라이브러리 중 전역 객체(예: window, global)나 특정 폴리필에 의존하는 것이 없는지 확인하고, 필요한 경우 동일한 방식으로 angular.json의 polyfills 배열에 추가하여 중앙 집중식으로 관리하는 것이 권장되는 베스트 프랙티스입니다.
Conclusion
Angular 18에서 발생하는 @angular/localize/init 폴리필 경고는 빌드 시스템이 최적화되는 과정에서 발생하는 자연스러운 마이그레이션 안내입니다. 일반 애플리케이션 개발자는 angular.json의 polyfills 배열에 패키지를 직접 등록하여 문제를 해결하고, 라이브러리 개발자는 TypeScript의 참조 지시어와 tsconfig.json을 활용하여 경고를 방지하시기 바랍니다.