# ng-packagr: Packaging Angular Libraries in APF

> ng-packagr compiles TypeScript library sources into Angular Package Format output, including FESM2022 bundles and type definitions. It fits Angular library publishers, but its Angular 22 peer requirements make version compatibility a primary adoption constraint.

**ng-packagr/ng-packagr** — Compile and package Angular libraries in Angular Package Format (APF)

- Repository: https://github.com/ng-packagr/ng-packagr
- Stars: 1,855 · Forks: 300
- Language: TypeScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/ng-packagr-ng-packagr

## Why ng-packagr Exists for Angular Library Publishers

ng-packagr addresses the final distribution stage of an Angular library. Library source code may be valid TypeScript and contain Angular components, but a package published to npm needs a structure that Angular tooling can consume consistently. The project targets Angular Package Format, or APF, rather than producing an arbitrary JavaScript bundle.

Its intended users are maintainers of component libraries and other publishable Angular packages. The build creates FESM2022 output, generates `.d.ts` files, and prepares a package that Angular CLI, Webpack, and ESM bundlers can consume. It also handles packaging concerns that individual library authors would otherwise have to coordinate, including templates, stylesheets, assets, secondary entry points, scoped or unscoped npm package names, and external dependencies.

The boundary is equally important. ng-packagr is a package compiler, not a general application bundler and not a replacement for Angular CLI application builds. It takes library sources and emits a distribution directory. The README documents `dist` as the output and `npm publish dist` as the subsequent publication command.

## The ng-packagr Compilation and Transformation Pipeline

The repository describes a custom transformation pipeline built with RxJS and Angular Dependency Injection concepts. That architecture is relevant because library compilation is more than invoking a TypeScript compiler. ng-packagr coordinates transformations related to Angular compilation, bundling, declarations, styles, assets, dependency handling, and the package layout required by APF.

The README identifies esbuild as a direct dependency, while the package metadata also includes `rolldown`, `rolldown-plugin-dts`, Sass tooling, PostCSS, and Angular compiler integration. Based on the documented feature set, library code is compiled into the FESM2022 form rather than shipped solely as source. Type definitions are produced separately as `.d.ts`, and templates and stylesheets are inlined. CSS processing includes SCSS compilation, vendor-specific prefixing, and asset embedding.

Configuration directs the compilation. A project supplies `ng-package.json`, and the command-line executable is `ng-packagr`, mapped to `./src/cli/main.js`. Supporting documentation covers entry-file selection, secondary entry points, dependency management, custom `tsconfig` usage, PostCSS, asset copying, and style include paths. These are separate extension points rather than undocumented switches in the short README.

## Installing ng-packagr and Building the First Package

Install `ng-packagr` as a development dependency in the Angular library project. The README gives this exact npm command:

```bash
npm install -D ng-packagr
```

Next, create an `ng-package.json` file in the library project. The README begins its example with a schema reference, but the displayed example is truncated, so it does not provide a complete copyable configuration:

```json
{
  "$schema": "./node_modules/ng-packagr/ng-package.schema.json",
   ...
}
```

The schema path points editors to the installed configuration schema. The omitted values remain project-specific and must be completed rather than copied from the incomplete example.

To make the build repeatable, add the documented package script. The relevant part of `package.json` is:

```json
{
  "scripts": {
    "build": "ng-packagr -p ng-package.json"
  }
}
```

Run that script with the package manager used by the README example:

```bash
$ yarn build
```

A successful invocation writes the packaged library to `dist`. Inspect that directory before publication, especially its package metadata, bundles, declarations, styles, and assets. The README then documents `npm publish dist` as the command for sending the generated directory to the npm registry.

## Runtime Compatibility Constraints in ng-packagr 22.3.0-next.2

The current package metadata makes compatibility unusually concrete. Version `22.3.0-next.2` requires Node.js `^22.22.3 || ^24.15.0 || >=26.0.0`. Its Angular compiler peer range is `^22.0.0 || ^22.2.0-next || ^22.3.0-next`, and its TypeScript peer range is `>=6.0 <6.1`. These constraints mean an Angular library cannot adopt this package solely because its existing Angular code is generally compatible.

`@angular/compiler-cli` and `tslib` are peer dependencies, so the consuming library must provide compatible versions. Tailwind CSS is listed as an optional peer dependency with support declared for versions 2, 3, and 4. It is the only peer dependency marked optional.

The release history also contains a distinction between prerelease and stable packages. Version `22.3.0-next.2` was released on 2026-10-01, while stable releases `22.2.4` and `22.2.3` were also released around the same period. An organization that forbids prerelease tooling should not select `22.3.0-next.2` merely because it is the version at the head of the repository. The README does not provide a compatibility matrix beyond the package metadata.

## APF Output Compared with Direct Bundler Consumption

The relevant alternative approaches are not another Angular version. They concern when compilation happens. A library publisher using ng-packagr compiles and organizes the package before npm consumers obtain it. The resulting APF package can then be consumed by Angular CLI, Webpack, or an ESM bundler. In this model, those downstream tools perform application bundling after importing the library.

By contrast, an application project can point Webpack or another ESM bundler at library source and let that application tool compile the source as part of its own dependency graph. That approach delegates packaging work downstream instead of producing an FESM2022 npm package with `.d.ts` declarations. The README names Webpack and ESM bundlers as consumers of ng-packagr output, but it does not document the configuration of a fully direct source-consumption workflow.

For a standalone npm library, these models have different release consequences. Downstream source compilation avoids preparing a completed APF distribution, while ng-packagr moves template, stylesheet, declaration, dependency, and bundle processing into the library release. The repository also mentions Nx and Bazel in a presentation about packaging Angular libraries, but the README does not state enough about either tool's configuration to present them as documented drop-in alternatives.

## Limits of ng-packagr for Non-Angular and Unfinished Packages

ng-packagr is a poor fit for a plain TypeScript package with no Angular packaging requirements. Its APF implementation, Angular compiler peer dependency, FESM2022 output, and Angular-specific handling of templates and styles all point toward a narrower purpose. Using it solely to invoke a general bundler would add an Angular-centered build tool without gaining a library format that the project needs.

It can also be the wrong choice when the local versions conflict with the declared peer ranges. The package metadata does not accept an unrestricted TypeScript release: for this version it requires `>=6.0 <6.1`. Node.js must also match one of the listed engine ranges. A team that cannot align its toolchain should inspect another release or another packaging approach rather than forcing installation.

The README does not document rollback, incremental build behavior, watch mode, or a complete `ng-package.json` example. It points to dedicated documents for advanced configuration, but the main page alone cannot establish how those features behave. The truncated configuration example is especially unsuitable as a production template.

## Maintenance Scope and the MIT License

The repository is not archived, and its last push was on 2026-10-16. The listed releases include a prerelease and two stable versions dated between 2026-09-30 and 2026-10-01, indicating recent changes to the package itself. That evidence supports current development activity, but it does not remove the upgrade cost created by narrow peer ranges.

Upgrading may require changes outside `package.json`. A new ng-packagr version can be coupled to a specific Angular compiler-cli range, TypeScript range, and Node.js engine range. Teams should compare those three boundaries before changing the build dependency. The repository uses pnpm for its own package management, with `packageManager` set to `pnpm@12.11.2`, but the README's consumer installation example uses npm and its script example uses Yarn.

The project is distributed under the MIT License. The repository includes a `LICENSE` file and marks `MIT` in `package.json`. That identifies the license associated with use and redistribution, but application-specific obligations and compatibility with a project's distribution policy still require review.

## Conclusion

Library maintainers that publish Angular components and need APF output should evaluate ng-packagr, especially when their Angular and TypeScript versions match the declared peer ranges. Consumers that only need to import the resulting library should use Angular CLI, Webpack, or an ESM bundler instead of adding the packaging tool. Before adoption, verify the Node.js engine range, Angular compiler-cli version, TypeScript version, entry file, style requirements, and npm publish contents in the generated `dist` directory.

## FAQ

### How do I install and run ng-packagr for an Angular library?

Install it with `npm install -D ng-packagr`, create `ng-package.json`, and run `ng-packagr -p ng-package.json`. The generated output is written to `dist`.

### What package format and output files does ng-packagr produce?

It implements Angular Package Format and produces FESM2022 bundles plus `.d.ts` type definitions. It also inlines templates and stylesheets and can process SCSS, vendor prefixes, and CSS assets.

### Which Node.js, Angular, and TypeScript versions support ng-packagr 22.3.0-next.2?

The package requires Node.js `^22.22.3 || ^24.15.0 || >=26.0.0`, `@angular/compiler-cli` `^22.0.0 || ^22.2.0-next || ^22.3.0-next`, and TypeScript `>=6.0 <6.1`.

## Sources

- [Issues](https://github.com/ng-packagr/ng-packagr/issues)
- [License: MIT](https://github.com/ng-packagr/ng-packagr/blob/main/LICENSE)
- [ng-packagr/ng-packagr on GitHub](https://github.com/ng-packagr/ng-packagr)
- [README](https://github.com/ng-packagr/ng-packagr/blob/main/README.md)
- [Releases](https://github.com/ng-packagr/ng-packagr/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ng-packagr-ng-packagr