feat(compiler-cli): add experimental support for fast type declaration emission #61334

jonathan-meier · 2025-05-14T13:18:18Z

PR Checklist

Please check if your PR fulfills the following requirements:

The commit message follows our guidelines: https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md
Tests for the changes have been added (for bug fixes / features)
Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

Bugfix
Feature
Code style update (formatting, local variables)
Refactoring (no functional changes, no api changes)
Build related changes
CI related changes
Documentation content changes
angular.dev application / infrastructure changes
Other... Please describe:

What is the current behavior?

No support for fast type declaration emission. Compilation fails with emitDeclarationOnly and noCheck TS compiler options set because the Angular compiler requires full type-checking information available for compilation.

What is the new behavior?

In declaration-only emission mode, the compiler extracts the type declarations (.d.ts) files without full type-checking, which is possible with sufficient type annotations on exports that can be ensured by the isolatedDeclarations TS compiler option.

This allows us to decouple type declaration emission from the actual full compilation doing the type-checking, thereby removing the edge between dependent TS files in the build action graph. In other words, the compilation of a TS file no longer indirectly depends on the compilation of all the TS files it imports through its dependency on their type declarations, because the type declarations themselves no longer depend on the compilation of their associated TS file.

Without the coupling between type declaration emission and compilation, compilation time of a TS project is no longer bound dependent on the depth of the TS dependency tree as we can now build the entire project with just two entirely parallel phases: 1) emit the type declarations of all TS files in parallel and 2) compile all TS files in parallel.

Since the Angular compiler adds static metadata fields to components, directives, modules, pipes and services based on their respective class annotations, it needs to actively partake in the type declaration emission in order to provide the types for these static fields in the declaration.

In this change, we add experimental support for a declaration-only emission mode based on the local compilation mode, which already operates without type-checking and access to external type information, i.e. the same environment as is required for declaration-only emisssion.

Apart from the same restrictions applied in local compilation mode, there are a few more restrictions imposed on code being compatible with this initial and experimental implementation:

No support for @NgModules using external references.
No support for hostDirectives in @Components and @Directives using external references.
No support for @Input annotations with transform.

Does this PR introduce a breaking change?

Yes
No

Other information

Internal references:

jonathan-meier · 2025-05-14T14:12:00Z

Questions for reviewers:

Is the terminology used for flags and error messages OK? I opted to use emitDeclarationOnly for the flags as it is the TS compiler option and "declaration-only emission" for user facing error messages. Do we want to mention "Gemini" in the flag name and code comments?
Is reusing the error codes fine like I did, or would you prefer me to introduce new error codes?

devversion

LGTM, very clean 🎉 — left some minor nits/questions

packages/compiler-cli/test/compliance/declaration/declaration_compile_spec.ts

packages/compiler-cli/test/compliance/test_helpers/check_type_declarations.ts

packages/compiler-cli/test/compliance/declaration/declaration_compile_spec.ts

packages/compiler-cli/test/ngtsc/declaration_compilation_spec.ts

packages/compiler-cli/test/compliance/test_cases/test_case_schema.json

devversion · 2025-05-14T14:30:24Z

@jonathan-meier Re your questions: The flag usage of declarationsOnly plus Gemini name sound very reasonable to me. As said, the explicit reference makes it easy to determine where this experimental flag is used & who built it IMO.

For the error codes. I think you're fine in general, but one thing to keep in mind is that some local compilation diagnostics trigger this logic in 1P: http://shortn/_ejJkrvNkin

…n emission In declaration-only emission mode, the compiler extracts the type declarations (.d.ts) files without full type-checking, which is possible with sufficient type annotations on exports that can be ensured by the `isolatedDeclarations` TS compiler option. This allows us to decouple type declaration emission from the actual full compilation doing the type-checking, thereby removing the edge between dependent TS files in the build action graph. In other words, the compilation of a TS file no longer indirectly depends on the compilation of all the TS files it imports through its dependency on their type declarations, because the type declarations themselves no longer depend on the compilation of their associated TS file. Without the coupling between type declaration emission and compilation, compilation time of a TS project is no longer bound dependent on the depth of the TS dependency tree as we can now build the entire project with just two entirely parallel phases: 1) emit the type declarations of all TS files in parallel and 2) compile all TS files in parallel. Since the Angular compiler adds static metadata fields to components, directives, modules, pipes and services based on their respective class annotations, it needs to actively partake in the type declaration emission in order to provide the types for these static fields in the declaration. In this change, we add experimental support for a declaration-only emission mode based on the local compilation mode, which already operates without type-checking and access to external type information, i.e. the same environment as is required for declaration-only emisssion. Apart from the same restrictions applied in local compilation mode, there are a few more restrictions imposed on code being compatible with this initial and experimental implementation: * No support for `@NgModule`s using external references. * No support for `hostDirectives` in `@Component`s and `@Directive`s using external references * No support for `@Input` annotations with `transform`.

jonathan-meier · 2025-05-14T16:26:58Z

Thanks for the pointer about using local compilation diagnostics in 1P! I'll keep reusing the error codes for now as I plan to support host directives in a follow-up which would remove the one instance using a local compilation error code.

devversion

LGTM

Reviewed-for: global-dev-infra-approvers

AndrewKushnir · 2025-05-14T18:07:52Z

packages/compiler-cli/src/ngtsc/core/api/src/public_options.ts

+   * The mode is experimental and specifically tailored to support fast type declaration emission
+   * for the Gemini app in g3.
+   */
+  _geminiAllowEmitDeclarationOnly?: boolean;


I'd propose renaming this config option (making it more geenric) for a couple of reasons:

That should avoid any confusion that the option represents a special capability for Gemini LLM itself.

If there is a desire or a need to test this behavior in other applications as a part of the experiment, it'd be confusing to use the current name.

Suggested change

* The mode is experimental and specifically tailored to support fast type declaration emission

* for the Gemini app in g3.

*/

_geminiAllowEmitDeclarationOnly?: boolean;

* The mode is experimental and specifically tailored to support fast type declaration emission

* for the Gemini app in g3 for the initial phase of the experiment.

*/

_experimentalAllowEmitDeclarationOnly?: boolean;

Note: since the PR has the "merge" label, please do not treat this comment as blocking. We can do a followup PR with an update if needed.

AndrewKushnir · 2025-05-14T19:06:25Z

Note: since the PR has the "merge" label, please do not treat this comment as blocking. We can do a followup PR with an update if needed.

Caretaker note: we've discussed this with Jonathan and the proposed plan forward is to merge the PR as is and create a followup PR with the config option rename.

AndrewKushnir · 2025-05-14T19:41:41Z

Caretaker note #2: the presubmit is "green" after rerunning some targets, this PR is ready for merge.

alxhub · 2025-05-14T21:07:40Z

This PR was merged into the repository by commit e62fb35.

The changes were merged into the following branches: main

…ssion Rename the flag `_geminiAllowEmitDeclarationOnly` to `_experimentalAllowEmitDeclarationOnly` as a follow-up on a comment in PR angular#61334.

…ssion (#61353) Rename the flag `_geminiAllowEmitDeclarationOnly` to `_experimentalAllowEmitDeclarationOnly` as a follow-up on a comment in PR #61334. PR Close #61353

angular-automatic-lock-bot · 2025-06-14T00:13:08Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

pullapprove bot requested a review from AndrewKushnir May 14, 2025 13:18

angular-robot bot added detected: feature PR contains a feature commit area: compiler Issues related to `ngc`, Angular's template compiler labels May 14, 2025

ngbot bot added this to the Backlog milestone May 14, 2025

devversion requested review from alxhub and devversion and removed request for AndrewKushnir May 14, 2025 13:21

devversion added action: review The PR is still awaiting reviews from at least one requested reviewer hotlist: google labels May 14, 2025

devversion approved these changes May 14, 2025

View reviewed changes

pullapprove bot requested review from AndrewKushnir and kirjs May 14, 2025 14:27

jonathan-meier force-pushed the gemini_isolated_declarations_b416702881 branch from f2cde4b to 1f23a3e Compare May 14, 2025 16:10

jonathan-meier force-pushed the gemini_isolated_declarations_b416702881 branch from 1f23a3e to 0aeceb1 Compare May 14, 2025 16:25

alxhub approved these changes May 14, 2025

View reviewed changes

pullapprove bot requested a review from mmalerba May 14, 2025 16:40

devversion approved these changes May 14, 2025

View reviewed changes

devversion removed request for AndrewKushnir, kirjs and mmalerba May 14, 2025 17:49

alxhub added action: merge The PR is ready for merge by the caretaker target: minor This PR is targeted for the next minor release and removed action: review The PR is still awaiting reviews from at least one requested reviewer labels May 14, 2025

AndrewKushnir reviewed May 14, 2025

View reviewed changes

alxhub closed this in e62fb35 May 14, 2025

jonathan-meier mentioned this pull request May 14, 2025

fix(compiler-cli): rename flag for enabling fast type declaration emission #61353

Closed

14 tasks

jonathan-meier mentioned this pull request May 23, 2025

fix(compiler-cli): disallow compiling with the emitDeclarationOnly TS compiler option enabled #61609

Open

14 tasks

angular-automatic-lock-bot bot locked and limited conversation to collaborators Jun 14, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(compiler-cli): add experimental support for fast type declaration emission #61334

feat(compiler-cli): add experimental support for fast type declaration emission #61334

Uh oh!

jonathan-meier commented May 14, 2025 •

edited

Loading

Uh oh!

jonathan-meier commented May 14, 2025

Uh oh!

devversion left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

devversion commented May 14, 2025

Uh oh!

jonathan-meier commented May 14, 2025

Uh oh!

devversion left a comment

Uh oh!

AndrewKushnir May 14, 2025 •

edited

Loading

Uh oh!

AndrewKushnir May 14, 2025

Uh oh!

AndrewKushnir commented May 14, 2025

Uh oh!

AndrewKushnir commented May 14, 2025

Uh oh!

alxhub commented May 14, 2025

Uh oh!

angular-automatic-lock-bot bot commented Jun 14, 2025

Uh oh!

Uh oh!

feat(compiler-cli): add experimental support for fast type declaration emission #61334

feat(compiler-cli): add experimental support for fast type declaration emission #61334

Uh oh!

Conversation

jonathan-meier commented May 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Checklist

PR Type

What is the current behavior?

What is the new behavior?

Does this PR introduce a breaking change?

Other information

Uh oh!

jonathan-meier commented May 14, 2025

Uh oh!

devversion left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

devversion commented May 14, 2025

Uh oh!

jonathan-meier commented May 14, 2025

Uh oh!

devversion left a comment

Choose a reason for hiding this comment

Uh oh!

AndrewKushnir May 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AndrewKushnir May 14, 2025

Choose a reason for hiding this comment

Uh oh!

AndrewKushnir commented May 14, 2025

Uh oh!

AndrewKushnir commented May 14, 2025

Uh oh!

alxhub commented May 14, 2025

Uh oh!

angular-automatic-lock-bot bot commented Jun 14, 2025

Uh oh!

Uh oh!

jonathan-meier commented May 14, 2025 •

edited

Loading

AndrewKushnir May 14, 2025 •

edited

Loading