Angular Compiler CLI (

ngtsc

) Architecture

Overview

packages/compiler-cli

ngtsc

tsc

ngtsc

@Component

@Directive

@Pipe

static ɵcmp = ...

Mental Model

1. Wrapper Pattern:

   NgtscProgram

   wraps the standard

   ts.Program

   . It intercepts calls to act as a drop-in replacement for standard tooling.
2. Traits System: Every class with an Angular decorator is considered a "Trait". The compiler manages the state of these traits through a state machine:
   • Pending: Detected but not processed.
   • Analyzed: Metadata extracted, template parsed (but dependencies not yet linked).
   • Resolved: Dependencies (directives/pipes in template) resolved, import cycles handled.
   • Skipped: Not an Angular class.
3. Lazy Analysis: Analysis only happens when necessary (e.g., when diagnostics are requested or emit is prepared).
4. Output AST: The compiler generates an intermediate "Output AST" (

   o.Expression

   ) for the generated code, which is then translated into TypeScript AST nodes during the emit phase.

Key Subsystems

1. Core Orchestration (

ngtsc/core

)

• NgtscProgram

  : The public API implementing

  api.Program

  . It manages the

  ts.Program

  and the

  NgCompiler

  .

• NgCompiler

  : The brain of the compiler. It orchestrates the compilation phases (Analysis, Resolution, Type Checking, Emit). It holds the

  TraitCompiler

  .

2. Trait Compilation (

ngtsc/transform

)

• TraitCompiler

  : Manages the lifecycle of "Traits". It iterates over source files, identifies decorated classes, and delegates to the appropriate

  DecoratorHandler

  .

• Trait

  : A state container for a class, holding its handler, analysis results, and resolution results.

3. Decorator Handlers (

ngtsc/annotations

)

• DecoratorHandler

  : An interface for handling specific decorators.

• ComponentDecoratorHandler

  : The most complex handler. It:
  • Extracts metadata (selector, inputs, outputs).
  • Parses the template.
  • Resolves used directives and pipes (

    R3TargetBinder

    ).
  • Generates the

    ɵcmp

    instruction.

• DirectiveDecoratorHandler

  ,

  PipeDecoratorHandler

  ,

  NgModuleDecoratorHandler

  : Handle their respective decorators.

4. Template Type Checking (

ngtsc/typecheck

)

• TemplateTypeChecker

  : Generates "Type Check Blocks" (TCBs). A TCB is a block of TypeScript code that represents the template's logic in a way

  tsc

  can understand and check for errors.

• TypeCheckBlock

  : The actual generated code that validates bindings, events, and structural directives.

5. Metadata & Scope (

ngtsc/metadata

,

ngtsc/scope

)

• MetadataReader

  : Reads Angular metadata from source files (using

  LocalMetadataRegistry

  ) and

  .d.ts

  files (using

  DtsMetadataReader

  ).

• ScopeRegistry

  : Determines the "compilation scope" of a component (which directives/pipes are available to it), handling

  NgModule

  transitive exports and Standalone Component imports.

6. Emit & Transformation (

ngtsc/transform

)

• ivyTransformFactory

  : A TypeScript transformer factory.

• IvyCompilationVisitor

  : Visits classes, triggers compilation via

  TraitCompiler

  , and collects the Output AST.

• IvyTransformationVisitor

  : Translates the Output AST into TypeScript AST, injects the

  static ɵ...

  fields, and removes the original decorators.

Compilation Phases

1. Construction:

   NgtscProgram

   creates

   NgCompiler

   , which sets up all registries and the

   TraitCompiler

   .
2. Analysis (

   analyzeSync

   ):
   • The

     TraitCompiler

     scans files.

   • DecoratorHandler

     s extract metadata and parse templates.
   • No cross-file resolution happens here (allowing for parallelism and caching).
3. Resolution (

   resolve

   ):

   • TraitCompiler

     resolves traits.
   • Components link their templates to specific Directives and Pipes (found via

     ScopeRegistry

     ).
   • Import cycles are detected and handled (e.g., via "remote scoping").
4. Type Checking:

   • TemplateTypeChecker

     creates TCBs for all components.
   • TypeScript diagnostics are retrieved for these TCBs.
5. Emit (

   prepareEmit

   ):

   • ivyTransformFactory

     is created.
   • TS

     emit

     is called.
   • The transformers run, injecting the compiled Ivy instructions into the JS/DTS output.

Important File Locations

• packages/compiler-cli/src/ngtsc/program.ts

  : Entry point (

  NgtscProgram

  ).

• packages/compiler-cli/src/ngtsc/core/src/compiler.ts

  : Core logic (

  NgCompiler

  ).

• packages/compiler-cli/src/ngtsc/transform/src/trait.ts

  : Trait state machine.

• packages/compiler-cli/src/ngtsc/annotations/component/src/handler.ts

  : Component compilation logic.

• packages/compiler-cli/src/ngtsc/typecheck/src/template_type_checker.ts

  : Type checking logic.

• packages/compiler-cli/src/ngtsc/transform/src/transform.ts

  : AST transformation logic.