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!

[dherges]

Hi @alan-agius4, this is great!

Now that TypeScript projects are growing in size and TypeScript itself is moving to the native Golang rewrite, driven by the need to optimize build times, I think that the approach to the new library builder is the way to go.

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`)

You have a very good point on incremental rebuilds in watch mode. The disk-heavy I/O in ng-packagr (from the early days) is a performance killer in larger projects.

That said, optimus-ui should also be a valid reference to run benchmarks.

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.

Fully agree. The disk-heavy I/O in ng-packagr (inherited from the early days) is a performance killer in larger projects.

I'll also agree that focusing on build times and therefore dropping auto-discovery of source files is a valid point.

• Single source of truth: Keeping all build configuration centralized in angular.json rather than scattered across dozens of nested configuration files.

Definetely. Centralizing this layout stops configuration drift across deeply nested directories.

---

I think, this is an incredible and much-needed milestone for the ecosystem!

I’ve been heavily experimenting with a similar in-memory architecture for ng-packagr (aiming at convergence with the CLI and bypassing disk I/O entirely). While I have been looking into esbuild as the bundler for libraries, I still think that hiding the mechanics of the internal build and packaging pipeline is favorable. While I'd loved to see a ng-packagr v2026, I've just started digging deeper into this new library builder and would love to contribute towards the adoption of the new library build system.

Seeing your benchmarks, especially the incremental TS/SCSS rebuild times hitting <250ms compared to legacy chains, completely validates that memory-bound compilation is the way forward for large-scale source repositories.

[alan-agius4]

Thanks for the feedback, @dherges! Also, thanks for pointing out optimus-ui, I'll definitely look into running benchmarks against it as well.

Just one clarification regarding the in memory aspect: ng-packagr already does intermediate compilation and bundling in memory, so disk I/O isn't actually the bottleneck there.

The performance gains we're seeing here, especially for incremental TS and SCSS rebuilds, mainly come from tighter integration with Angular's compiler host and caching infrastructure, along with a direct async rebuild pipeline that eliminates the orchestration overhead of the reactive RxJS transform architecture and per entry point sub pipelines.

[thekhegay]

@alan-agius4 about entryPoints: I put up the glob version as a draft #34127.

An entry point that silently doesn't get published was the part that worried me most, so I wanted something concrete to discuss rather than just an issue.

On ngwr these two lines replace the 230-line map, the output is identical to the explicit map, and the scan takes ~10ms.

It's a draft since there's nothing to merge it into yet. Happy to change approach or close it if you'd rather do it differently.

[dherges]

Just one clarification regarding the in memory aspect: ng-packagr already does intermediate compilation and bundling in memory, so disk I/O isn't actually the bottleneck there.

That makes total sense. I was exploring the disk I/O of the source discovery and the .d.ts bundling as potential bottlenecks.

The performance gains we're seeing here, especially for incremental TS and SCSS rebuilds, mainly come from tighter integration with Angular's compiler host and caching infrastructure, along with a direct async rebuild pipeline that eliminates the orchestration overhead of the reactive RxJS transform architecture and per entry point sub pipelines.

So you're saying: sharing the compiler host and the stylesheet bundling across multiple entry points is the real difference. Right?

To better understand the approach: is the speedup here just removing RxJS transforms, or removing RxJS transforms plus additional benefit that come along with it?

[alan-agius4]

Thanks for putting together #34127 so quickly, @thekhegay! Having a concrete implementation to look at makes evaluating the ergonomics much easier, and the data on ngwr is definitely interesting. That said, we are not sure yet if this is the direction we want to take, as there are trade offs to consider around determinism and configuration clarity. Let us keep this PR focused on landing the initial builder implementation first, and we can continue evaluating whether pattern support is something we want to pursue.

@dherges That is definitely a large part of it, but the speedup comes from several specific architectural changes beyond just removing the RxJS transform layer:

1. Shared Stylesheet Bundling:
   • In ng-packagr, each entry point instantiates its own StylesheetProcessor.
   • Here, a single ComponentStylesheetBundler is shared across all entry points, allowing esbuild state and Sass worker pool caches to be reused across the entire project and invalidated centrally.

2. Public API Invalidation via Declaration Hashing:
   • We hash the emitted .d.ts bundle (lastDtsHash). Downstream entry points are only marked dirty if the public type declarations actually changed. Internal implementation changes in an upstream entry point will not trigger recompilation of dependents.

3. Dedicated Worker Pool for Production Builds:
   • For non watch builds, entry points within each topological batch are compiled across worker threads via compilerWorkerPool.

4. Single Pass Output Emission:
   • Rather than writing files throughout individual transform steps, all output files across all entry points (bundles, declarations, sourcemaps, manifests, assets) are written in a single batched pass at the end.

5. Direct Async Pipeline:
   • Removing injection-js and the RxJS transform chain eliminates the scheduling and subscription overhead across dozens or hundreds of entry points.