Angular Package Format (APF) is the official standard that makes Angular libraries "just work" for everyone—across different projects, build tools, and Angular versions.
When building Angular libraries, you want your package to "just work" for everyone—across different projects, build tools, and Angular versions. The Angular Package Format (APF) is the official standard that makes this possible.
Angular is more than a framework—it's an ecosystem. Libraries are everywhere: UI kits, utilities, data layers, and more. But not all npm packages are created equal! Without a standard, library consumers would face:
APF solves these problems by defining how Angular libraries should be structured, built, and published.
APF is a specification—a set of rules for what files, formats, and metadata an Angular library should include. It is not a tool, but most tools (like Angular CLI and ng-packagr) know how to produce APF-compliant packages.
Angular libraries have evolved alongside the framework itself. Here's a quick timeline:
sideEffects: false
for tree-shaking, and better CLI support.tslib
required as a dependency for helper functions.A typical APF-compliant package looks like this:
my-angular-lib/
├── README.md
├── package.json
├── index.d.ts
├── fesm2022/
│ └── my-angular-lib.mjs
└── ...
Key elements:
package.json
: The heart of your package. Includes special fields:
type: "module"
(ESM by default)sideEffects: false
(enables tree-shaking)exports
(controls public entry points)peerDependencies
(e.g., @angular/core
, tslib
)index.d.ts
: Bundled TypeScript types for your public API.fesm2022/
: Flattened ES2022 module (main entry point for consumers).my-angular-lib/testing
for test utilities or my-angular-lib/button
for a button component.FESM stands for "Flattened ES Module"—a single file that contains your whole library, making builds faster and bundles smaller.
package.json
FieldsA well-formed package.json
is crucial for APF. Here are the most important fields:
{
"name": "my-angular-lib",
"type": "module",
"sideEffects": false,
"exports": {
".": {
"types": "./index.d.ts",
"esm2022": "./fesm2022/my-angular-lib.mjs"
},
"./testing": {
"types": "./testing/index.d.ts",
"esm2022": "./fesm2022/my-angular-lib-testing.mjs"
}
},
"peerDependencies": {
"@angular/core": ">=16.0.0",
"tslib": ">=2.0.0"
}
}
exports
: Controls what consumers can import. Prevents deep imports into internal files.sideEffects: false
: Tells bundlers your code has no global side effects, enabling tree-shaking.peerDependencies
: Ensures consumers use compatible Angular and tslib versions.Tree-shaking is the process of removing unused code from your final bundle. APF helps by:
sideEffects: false
This means consumers only get the code they actually use—no more, no less.
The easiest way is to use Angular CLI and ng-packagr (or Nx):
ng generate library my-lib
ng build my-lib
The both tools will generate an APF-compliant package and we already did it in the previous lesson.
Large libraries often split features into sub-packages (e.g., @angular/material/button
). APF supports this via secondary entry points:
package.json
, and type definitions.exports
field in the root package.json
maps these entry points.Example:
"exports": {
".": { ... },
"./button": {
"types": "./button/index.d.ts",
"esm2022": "./fesm2022/my-angular-lib-button.mjs"
}
}
This lets consumers import only what they need:
import { MyButtonComponent } from 'my-angular-lib/button';
We will use secondary entry points in the next lesson!
my-lib/esm2022/foo
). Always import from the public API.tslib
and Angular peer dependencies.And allways use the ng-packagr
to build your library! It will
generate an APF-compliant package for you. ng-packagr
is the only tool that fully
supports APF!
APF evolves with Angular. As the framework targets newer JavaScript versions and build tools, APF will continue to simplify and modernize. Staying up to date with Angular CLI and its generators is the best way to ensure your library remains compatible.
While ng-packagr's main job is to implement the Angular Package Format (APF), it also provides a rich set of features that make building and publishing Angular libraries much easier and more robust.
Here's a quick overview of what it offers out of the box:
.d.ts
)🎁 Pre-order now — "Angular UI Kit"
We’re launching our first interactive course on ng.guide, where you'll build a production-grade UI library using real-world Angular practices.
💸 Early-bird price: $99 (was $125) — available only before launch.
Reserve your access now and get hands-on with how Angular works at scale.