환경설정

Angular 컴파일러 옵션

사전 컴파일(AOT)을 사용할 때 TypeScript 설정 파일에 Angular 컴파일러 옵션을 지정하여 애플리케이션이 컴파일되는 방식을 제어할 수 있습니다.

Angular 옵션 객체인 angularCompilerOptions는 TypeScript 컴파일러에 표준 옵션을 제공하는 compilerOptions 객체와 같은 계층에 있습니다.

tsconfig.json

{
  "compileOnSave": false,
  "compilerOptions": {
    // ...
  },
  "angularCompilerOptions": {
    "enableI18nLegacyMessageIdFormat": false,
    "strictInjectionParameters": true,
    // ...
  }
}

extends로 설정 상속하기

TypeScript 컴파일러와 마찬가지로 Angular AOT 컴파일러도 TypeScript 설정 파일의 angularCompilerOptions 섹션에서 extends를 통한 상속을 지원합니다. extends 프로퍼티는 compilerOptions, angularCompilerOptions와 나란히 최상위 수준에 위치합니다.

TypeScript 설정은 extends 프로퍼티를 사용해 다른 파일의 설정을 상속할 수 있습니다. 기본 파일의 설정 옵션을 먼저 불러온 다음, 이를 상속하는 설정 파일의 옵션으로 덮어씁니다.

예를 들면 다음과 같습니다.

tsconfig.app.json

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./out-tsc/app",
    // ...
  },
  // ...
  "angularCompilerOptions": {
    "preserveWhitespaces": true,
    // ...
  }
}

자세한 내용은 TypeScript 핸드북을 참고하세요.

템플릿 옵션

Angular AOT 컴파일러를 설정할 때 다음 옵션을 사용할 수 있습니다.

annotationsAs 옵션

트리 셰이킹을 개선하기 위해 Angular 전용 어노테이션을 출력하는 방식을 변경합니다. Angular와 관련 없는 어노테이션에는 영향을 주지 않습니다. static fields 또는 decorators를 지정할 수 있습니다. 기본값은 static fields입니다.

  • 기본적으로 컴파일러는 데코레이터를 클래스의 정적 필드로 대체합니다. 이를 통해 Closure 컴파일러와 같은 고급 트리 셰이킹 도구가 사용하지 않는 클래스를 제거할 수 있습니다.

  • decorators를 지정하면 데코레이터를 그대로 두므로 컴파일이 더 빨라집니다. TypeScript는 __decorate 헬퍼를 호출하는 코드를 출력합니다. 런타임 리플렉션에는 --emitDecoratorMetadata를 사용하세요.

    HELPFUL: 이 경우 생성된 코드에 트리 셰이킹이 제대로 적용되지 않습니다.

annotateForClosureCompiler 옵션

true이면 Tsickle을 사용해 출력되는 JavaScript에 Closure 컴파일러가 필요로 하는 JSDoc 주석을 추가합니다. 기본값은 false입니다.

compilationMode 옵션

사용할 컴파일 모드를 지정합니다. 다음 모드를 사용할 수 있습니다.

모드 설명
'full' 현재 사용하는 Angular 버전에 맞춰 완전히 AOT 컴파일된 코드를 생성합니다.
'partial' 배포할 라이브러리에 적합한 안정적인 중간 형식의 코드를 생성합니다.

기본값은 'full'입니다.

대부분의 애플리케이션에는 'full' 컴파일 모드가 적합합니다.

npm 패키지처럼 독립적으로 배포하는 라이브러리에는 'partial'을 사용하세요. 'partial' 컴파일은 안정적인 중간 형식을 출력하므로 라이브러리와 다른 Angular 버전으로 빌드된 애플리케이션에서 라이브러리를 사용하기에 더 적합합니다. 모노레포처럼 애플리케이션과 함께 "HEAD"에서 빌드되고 같은 Angular 버전을 사용하는 라이브러리는 버전 불일치 위험이 없으므로 'full'을 사용할 수 있습니다.

disableTypeScriptVersionCheck 옵션

true이면 컴파일러가 TypeScript 버전을 확인하지 않으며 지원하지 않는 TypeScript 버전을 사용해도 오류를 보고하지 않습니다. 지원하지 않는 TypeScript 버전은 동작이 정의되지 않을 수 있으므로 권장하지 않습니다. 기본값은 false입니다.

enableI18nLegacyMessageIdFormat 옵션

템플릿에서 i18n 속성으로 표시한 메시지에 대해 Angular 템플릿 컴파일러가 기존 형식의 ID를 생성하도록 합니다. 지역화를 위해 메시지를 표시하는 방법은 번역할 텍스트 표시하기를 참고하세요.

프로젝트가 이전에 기존 형식의 ID로 생성한 번역에 의존하는 경우가 아니라면 이 옵션을 false로 설정하세요. 기본값은 true입니다.

Ivy 이전의 메시지 추출 도구는 추출한 메시지 ID에 여러 가지 기존 형식을 사용했습니다. 이러한 메시지 형식에는 공백 처리 문제와 템플릿 원본 HTML의 정보에 의존하는 문제 등이 있습니다.

새 메시지 형식은 공백 변경에 더 견고하며, 모든 번역 파일 형식에서 동일하고, $localize 호출로 직접 생성할 수 있습니다. 따라서 애플리케이션 코드의 $localize 메시지에 컴포넌트 템플릿의 동일한 i18n 메시지와 같은 ID를 사용할 수 있습니다.

IMPORTANT: 이 옵션은 @angular-devkit/build-angular:browser 빌더에서만 지원합니다. @angular/build:application 빌더(esbuild)를 사용할 때는 이 옵션이 적용되지 않으며, 이 설정과 관계없이 항상 새로운 십진수 메시지 ID 형식을 사용합니다.

enableResourceInlining 옵션

true이면 모든 @Component 데코레이터의 templateUrl과 styleUrls 프로퍼티를 인라인 콘텐츠가 들어 있는 template과 styles 프로퍼티로 대체합니다.

이 옵션을 활성화하면 ngc가 출력하는 .js 파일에 지연 로딩할 템플릿이나 스타일 URL이 포함되지 않습니다.

Angular CLI로 생성한 라이브러리 프로젝트에서는 개발 설정의 기본값이 true입니다.

flatModuleId 옵션

플랫 모듈을 가져올 때 사용할 모듈 ID입니다(flatModuleOutFile에 파일 이름을 지정한 경우). 템플릿 컴파일러가 생성하는 참조는 플랫 모듈에서 심벌을 가져올 때 이 모듈 이름을 사용합니다. flatModuleOutFile을 지정하지 않으면 무시됩니다.

flatModuleOutFile 옵션

출력 파일 이름을 지정하면 해당 이름으로 플랫 모듈 인덱스와 메타데이터를 생성합니다. @angular/core, @angular/common과 비슷한 방식으로 패키징되는 플랫 모듈을 만들 때 사용합니다. 이 옵션을 사용할 때 라이브러리의 package.json은 라이브러리 인덱스 파일 대신 생성된 플랫 모듈 인덱스를 참조해야 합니다.

라이브러리 인덱스에서 내보낸 심벌에 필요한 모든 메타데이터를 담은 .metadata.json 파일을 하나만 생성합니다. 생성된 .ngfactory.js 파일에서는 플랫 모듈 인덱스를 사용해 심벌을 가져옵니다. 여기에는 라이브러리 인덱스의 공개 API와 숨겨진 내부 심벌이 모두 포함됩니다.

기본적으로 files 필드에 지정한 .ts 파일을 라이브러리 인덱스로 간주합니다. .ts 파일을 여러 개 지정하면 libraryIndex를 사용해 사용할 파일을 선택합니다. libraryIndex 없이 .ts 파일을 여러 개 지정하면 오류가 발생합니다.

지정한 flatModuleOutFile 이름으로 플랫 모듈 인덱스 .d.ts와 .js를 생성하며, 위치는 라이브러리 인덱스 .d.ts 파일과 같습니다.

예를 들어 라이브러리가 public_api.ts 파일을 모듈의 라이브러리 인덱스로 사용한다면 tsconfig.json의 files 필드는 ["public_api.ts"]가 됩니다. 이때 flatModuleOutFile 옵션을 "index.js" 등으로 설정하면 index.d.ts와 index.metadata.json 파일이 생성됩니다. 라이브러리 package.json의 module 필드는 "index.js", typings 필드는 "index.d.ts"가 됩니다.

generateCodeForLibraries 옵션

true이면 대응하는 .metadata.json 파일이 있는 .d.ts 파일에 대해 팩토리 파일(.ngfactory.js와 .ngstyle.js)을 생성합니다. 기본값은 true입니다.

false이면 .ts 파일에 대해서만 팩토리 파일을 생성합니다. 팩토리 요약 정보를 사용할 때는 false로 설정하세요.

preserveWhitespaces 옵션

기본값인 false이면 컴파일된 템플릿에서 빈 텍스트 노드를 제거하여 출력되는 템플릿 팩토리 모듈의 크기를 줄입니다. 빈 텍스트 노드를 유지하려면 true로 설정하세요.

HELPFUL: 하이드레이션을 사용할 때는 기본값인 preserveWhitespaces: false를 사용하는 것이 좋습니다. tsconfig에 preserveWhitespaces: true를 추가해 공백을 유지하면 하이드레이션에서 문제가 발생할 수 있습니다. 이 설정은 아직 완전히 지원되지 않습니다. 서버와 클라이언트의 tsconfig 파일에서도 이 설정이 일치하도록 해야 합니다. 자세한 내용은 하이드레이션 가이드를 참고하세요.

skipMetadataEmit 옵션

true이면 .metadata.json 파일을 생성하지 않습니다. 기본값은 false입니다.

.metadata.json 파일에는 .ts 파일의 정보 중 TypeScript 컴파일러가 생성하는 .d.ts 파일에 포함되지 않지만 템플릿 컴파일러에는 필요한 정보가 담깁니다. 예를 들어 컴포넌트 템플릿과 같은 어노테이션 내용이 이에 해당하며, TypeScript는 이 정보를 .js 파일에는 출력하지만 .d.ts 파일에는 출력하지 않습니다.

팩토리 요약 정보에는 .metadata.json 파일의 정보 사본이 포함되므로 팩토리 요약 정보를 사용할 때는 이 옵션을 true로 설정할 수 있습니다.

TypeScript의 --outFile 옵션을 사용할 때는 메타데이터 파일이 이 TypeScript 출력 형식에 적합하지 않으므로 true로 설정하세요. Angular 커뮤니티에서는 Angular와 함께 --outFile을 사용하는 것을 권장하지 않습니다. 대신 webpack과 같은 번들러를 사용하세요.

skipTemplateCodegen 옵션

true이면 .ngfactory.js와 .ngstyle.js 파일을 출력하지 않습니다. 이 옵션은 템플릿 컴파일러의 대부분을 끄고 템플릿 진단 보고를 비활성화합니다.

템플릿 컴파일러가 npm 패키지와 함께 배포할 .metadata.json 파일을 생성하도록 할 때 사용할 수 있습니다. 이렇게 하면 npm에 배포할 수 없는 .ngfactory.js와 .ngstyle.js 파일의 생성을 피할 수 있습니다.

Angular CLI로 생성한 라이브러리 프로젝트에서는 개발 설정의 기본값이 true입니다.

strictMetadataEmit 옵션

true이고 "skipMetadataEmit"이 false이면 오류를 .metadata.json 파일에 보고합니다. 기본값은 false입니다. "skipMetadataEmit"이 false이고 "skipTemplateCodegen"이 true일 때만 사용하세요.

이 옵션은 npm 패키지에 번들링하기 위해 출력한 .metadata.json 파일을 검증하기 위한 것입니다. 검증이 엄격하므로 템플릿 컴파일러에서 사용하면 오류가 발생하지 않는 메타데이터에 대해서도 오류가 발생할 수 있습니다. 내보내는 심벌의 문서화 주석에 @dynamic을 포함하면 해당 심벌에 대해 이 옵션이 발생시키는 오류를 억제할 수 있습니다.

.metadata.json 파일에 오류가 포함되어 있어도 유효합니다. 템플릿 컴파일러는 이 메타데이터를 사용해 어노테이션 내용을 결정할 때 이러한 오류를 보고합니다. 메타데이터 수집기는 어떤 심벌이 어노테이션에 사용되도록 설계되었는지 예측할 수 없으므로, 내보내는 심벌의 메타데이터에 미리 오류 노드를 포함합니다. 이후 템플릿 컴파일러는 이 심벌이 사용될 경우 오류 노드를 활용해 오류를 보고할 수 있습니다.

라이브러리를 사용하는 쪽에서 심벌을 어노테이션에 사용하려고 하더라도 템플릿 컴파일러는 일반적으로 오류를 미리 보고하지 않습니다. 실제로 심벌을 사용한 뒤에 오류를 보고합니다. 이 옵션을 사용하면 라이브러리 빌드 단계에서 이러한 오류를 감지할 수 있으며, Angular 라이브러리 자체를 제작할 때도 사용합니다.

Angular CLI로 생성한 라이브러리 프로젝트에서는 개발 설정의 기본값이 true입니다.

strictInjectionParameters 옵션

true이면 전달된 인자의 주입 타입을 확인할 수 없을 때 오류를 보고합니다. false이면 @Injectable로 표시한 클래스의 생성자 인자 중 타입을 확인할 수 없는 인자에 대해 경고를 생성합니다. 권장값은 true이지만 기본값은 false입니다.

Angular CLI 명령어 ng new --strict를 사용하면 생성한 프로젝트의 설정에서 이 값이 true로 설정됩니다.

strictTemplates 옵션

true이면 엄격한 템플릿 타입 검사를 활성화합니다.

이 옵션이 활성화하는 엄격성 플래그로 특정 종류의 엄격한 템플릿 타입 검사를 켜거나 끌 수 있습니다. 템플릿 오류 해결하기를 참고하세요. 기본값은 true입니다.

strictStandalone 옵션

true이면 컴포넌트, 디렉티브, 파이프가 독립형이 아닐 때 오류를 보고합니다.

trace 옵션

true이면 템플릿을 컴파일하는 동안 추가 정보를 출력합니다. 기본값은 false입니다.

typeCheckHostBindings 옵션

true이면 컴포넌트와 디렉티브의 host 객체 리터럴 및 @HostBinding/@HostListener 데코레이터 안에 있는 표현식의 타입 검사를 활성화합니다. 기본값은 true입니다.

명령줄 옵션

대부분의 경우 Angular CLI를 통해 Angular 컴파일러를 간접적으로 사용합니다. 특정 문제를 디버깅할 때는 Angular 컴파일러를 직접 실행하는 것이 도움이 될 수 있습니다. @angular/compiler-cli npm 패키지가 제공하는 ngc 명령어로 명령줄에서 컴파일러를 호출할 수 있습니다.

ngc 명령어는 TypeScript의 tsc 컴파일러 명령어를 감싸는 래퍼입니다. Angular 컴파일러는 주로 tsconfig.json으로 설정하며, Angular CLI는 주로 angular.json으로 설정합니다.

설정 파일 외에도 tsc 명령줄 옵션으로 ngc를 설정할 수 있습니다.