Angular Package Format (APF) is the npm distribution format Angular uses for framework and library packages. It defines how a package exposes JavaScript, TypeScript declarations, entrypoints, and metadata so Angular applications and other build tools can resolve and optimize it. For a library intended for independent publication, build with Angular CLI and ng-packagr, use partial compilation, and publish the production package output.
What is the Angular Package Format?
APF describes the files and package metadata used to distribute Angular packages on npm. It is not a separate runtime or framework: it is the structure that helps package managers, TypeScript, and build tools find a library’s public code and types. Angular’s first-party packages and many third-party libraries use it. The specification evolves alongside Angular major versions, so package authors should follow the current Angular Package Format guide rather than assume an older package layout remains current.
As an Amazon Associate I earn from qualifying purchases.
APF is designed to work with different JavaScript application build tools. It aims to make packages resolvable and optimizable while supporting application builds and library development.
How an APF package exposes code and types
The package’s package.json is central to resolution. In the current Angular guide’s simplified @angular/core example, the package includes flattened ESM files under fesm2022/, source maps, and TypeScript declarations under types/. The manifest’s exports map connects public import paths to runtime code and declaration files; conditional exports can also expose non-JavaScript assets.
#1 Best Overall
type: "module"identifies the package as using ESM. ESM describes its import/export module system; it is distinct from the JavaScript language level.exportsis the modern map for public entrypoints and their files.sideEffectscommunicates side-effect behavior to help optimizers, and should reflect what the package actually does.moduleandtypingsare legacy manifest fields shown for compatibility with tools that do not useexports; Angular characterizes them as deprecated as ecosystem support forexportsrolls out.
The guide’s documented JavaScript language level is ES2022. Application tooling such as Angular CLI can down-level output for the browser targets configured by the consuming application. That does not change the meaning of ESM: one concerns module syntax, the other language features.
What is an Angular package entrypoint?
An entrypoint is a public import path into a package. The primary entrypoint is the package root; secondary entrypoints expose other logically distinct capabilities at subpaths. For example, Angular documents @angular/core/testing, while a library might expose my-lib/button. Each entrypoint should have a public API, and consumers should use these documented paths rather than deep-import implementation files.
Entrypoints are also potential lazy-loading boundaries because bundlers can split code at ES-module boundaries. APF commonly flattens each entrypoint into one ES module, so a single entrypoint can constrain splitting granularity. Group related functionality into the smallest sensible logical entrypoints; a library with one coherent purpose may still be best served by just one. Separate every class only when that boundary represents a useful public capability.
Recommended Free Tools
Define and organize public APIs
In a CLI-generated library, public-api.ts specifies what consumers can import. To add a secondary entrypoint, create a directory with its own ng-package.json and public API file; ng-packagr derives the package subpath from that directory. When one entrypoint refers to another, use the package import path, not a relative file import, and avoid circular dependencies between entrypoints.
Rank #3
Why published libraries use partial compilation
Angular’s APF guide says libraries must be published in partial compilation mode. Partial compilation emits a stable intermediate representation rather than code tied to one exact Angular runtime version. During the consuming application’s build, Angular CLI uses that application’s Angular compiler to convert the library output into fully compiled code.
The compiler options distinguish partial from full. The former is intended for published libraries that may be consumed by applications using different Angular versions. Full compilation emits AOT-compiled output for the Angular version in use; it can suit a library built alongside its application, such as in a monorepo, when both use the same Angular version and version skew is not a concern. Angular cautions against publishing full-Ivy output as a general optimization: it is version-specific, and its generated instructions are not a public API.
How to build an Angular library for npm
Angular’s library creation guide recommends Angular CLI and npm. The CLI library builder uses ng-packagr; current CLI documentation identifies @angular/build:ng-packagr as the builder that produces an Angular library adhering to APF. A typical workflow is:
- Create the library: use the Angular CLI library-generation workflow described in the library creation guide.
- Define its public API: configure the library with
ng-package.json, which identifies the entry file, commonlysrc/public-api.ts. The generated library also has package metadata and a TypeScript configuration. - Set compilation for distribution: use partial compilation for an independently published library, and ensure Angular framework dependencies are declared as peer dependencies.
- Build the production package: use the library’s CLI build target with its production configuration. The Angular CLI build documentation describes the ng-packagr builder.
- Inspect and publish: review the generated
distpackage for its declarations, assets, README, and other promised files, then publish that production output to npm.
Additional files such as Sass mixins or CSS can be included, but they need to be exposed through package exports to be available as supported package paths. Angular libraries are distributed through npm; consumers install them with a package manager and import the documented API. For many libraries, ng add can also run schematics to assist with project integration.
Declare Angular packages as peers
Angular’s library guide recommends placing Angular dependencies used by the library in peerDependencies. This lets the application and library share the same Angular module instance. Shipping @angular/core as an ordinary library dependency can introduce a duplicate instance and cause runtime problems.
How to evaluate an APF library
When reviewing a package or choosing among libraries, inspect the package itself rather than relying only on its description:
Quick Recap
- Public API: Are supported import paths documented and sensibly grouped, or do consumers need brittle deep imports?
- Compilation compatibility: Is independently published code partially compiled, and does its Angular peer dependency range match the applications it intends to support?
- Resolver metadata: Does
exportsmap each public path to runtime code and types? Are legacy fields present only where compatibility requires them? - Optimization behavior: Is
sideEffectsaccurate, and do the entrypoints let consumers import the capabilities they need? - Package completeness: Does the production package contain declarations, assets, documentation, and other files the library promises?
- Dependency ownership: Are Angular framework packages declared as peers where needed?
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
