feat(@angular/build): add library builder

[alan-agius4]

PR Checklist

Please check to confirm your PR fulfills the following requirements:

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

PR Type

• Feature

What is the current behavior?

Currently, there is no native @angular/build:library builder in @angular/build.

Issue Number: N/A

What is the new behavior?

Add a new native @angular/build:library builder providing a modern, high-performance compilation and packaging pipeline.

Does this PR introduce a breaking change?

• No

Other information

[alan-agius4]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a new library builder (@angular/build:library) designed to compile, bundle, and package Angular libraries in compliance with the Angular Package Format (APF). It includes features such as incremental compilation, watch mode, asset copying, secondary entry point resolution, and package.json generation. The review feedback highlights a few critical areas for improvement: ensuring the package name is updated in options when package.json changes in watch mode, optimizing startup by avoiding redundant reads of package.json, and capturing and propagating stylesheet compilation warnings to the user.

[gemini-code-assist]

Code Review

This pull request introduces a new library builder for Angular, enabling the compilation, bundling, and packaging of libraries in accordance with the Angular Package Format (APF). The changes include the core builder logic, a dependency graph scanner for entry points, an incremental compilation pipeline, and support for secondary entry points. My review highlights performance optimizations for the dependency predicate and file change detection logic, which are critical for maintaining build speed in larger projects.

[thekhegay]

Hello! @alan-agius4 thank you for your great job.

A few questions (cause i'm planning to test new builder):

1. Is secondary entry points will stay discovered from nested ng-package.json files or move to explicit config? And does the builder keep allowing barrel index.ts beside non-index entryFile? (ng-packagr rejected that for awhile)
2. ng-packagr resolves @use 'lib/button' through sass condition in the package exports map and libs ship per-entry-point stylesheets that way. Is that part of plan?
3. Is the types declations building equivalent to what rolldown-plugin-dts does, including d.ts for each entry point?
4. Is the intent that ng-packagr statys supported for a while with a schematic later or this is straight replacement?

If it will help: happy to report back what brakes. ngwr using 227 entry points, per-entry-point sass, harnesses in secondary entry points

[alan-agius4]

@thekhegay, thanks for the questions! Here are the details:

1. Secondary entry points & barrels: Entry points are configured explicitly in angular.json under entryPoints (no nested ng-package.json discovery). Any entry file name (including index.ts alongside barrels) is supported without naming restrictions.
2. Sass exports: Custom conditions in your source package.json exports (like sass or style) are preserved and merged into the generated manifests, so @use 'lib/button' continues to work.
3. Types bundling: Yes, declaration bundling uses rolldown-plugin-dts to emit a single .d.ts bundle per entry point.
4. ng-packagr transition: ng-packagr will remain supported alongside the new builder; it won't be replaced immediately, and a migration schematic will be provided later.

Testing on a project with 227 entry points, per-entry Sass, and secondary test harnesses would be fantastic and extremely helpful please feel free to share any issues you run into!

[thekhegay]

@alan-agius4 out of scope of this PR, just flagging it: about entryPoints map.

ngwr has 228 entry points (99 of them nested, like icon/adapters/lucide or button/testing), so map is ~230 lines in angular.json that mirror folder layout.

The part that worries me isn't size - adding an entry point becomes two steps instead of one, and forgetting second fails silently - entry point just is not published.

Would a glob value be on the table ("*": "projects/lib/*/public-api.ts", key from the matched folder) or discovery kept as opt-in mode? If not, having migration schematic generate map from existing ng-package.json files would cover most of it

Sorry for dropping this here - discussions are off in this repor and i wasnt sure where question belongs. happy to move it to and issue if you'd rather keep this PR clean

P.S. I have started building ngwr against this branch and running tests against output. If i hit anything i ll file if as an issue with reproductin rather than comment in this PR.

[alan-agius4]

I actually just tested this against ngwr (228 entry points) and ran some benchmarks comparing @angular/build:library against ng-packagr. The numbers look very promising especially for incremental rebuilds in watch mode:

Scenario	ng-packagr (v22.1.1)	@angular/build:library	Result
Clean Build	37.10s (38.36s wall)	34.41s (37.47s wall)	~2.7s faster (@angular/build)
Watch: Cold Initial Build	33.51s	32.93s	~0.6s faster (@angular/build)
Watch: Incremental TS Rebuild (button.ts)	282ms – 634ms	149ms (137ms compile)	~2x to 4.2x faster (@angular/build)
Watch: Incremental Sass Rebuild (breadcrumbs.scss)	582ms	215ms (119ms compile)	~2.7x faster (@angular/build)

To address your questions:

1. Migration Schematic:
   Yes, an automated migration schematic (ng update) will definitely be provided. It will scan existing ng-package.json files and automatically populate the entryPoints map in angular.json, so you won't need to manually configure them when upgrading.

2. Explicit Entry Points vs. Discovery / Globs:
   The decision to use explicit entryPoints was driven by:

   • Performance and determinism: Avoiding recursive filesystem traversal/scanning on every build and watcher startup.
   • Single source of truth: Keeping all build configuration centralized in angular.json rather than scattered across dozens of nested configuration files.

   That said, your point about DX and the risk of silent omission when adding new entry points in large libraries is very valid.

   • Supporting glob patterns (e.g. "./*": "projects/lib/*/public-api.ts") or an opt-in discovery mode is definitely something we can explore as a follow-up feature.
   • We could also look into CLI schematics (e.g. ng generate library-entry-point) to ensure newly created entry points are automatically registered.

Please feel free to open issues with any reproductions or edge cases you encounter while testing your feedback is greatly appreciated!