iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To create an Angular library, run ng generate library my-lib inside an Angular workspace, define what consumers can import through its public-api.ts file, build it with ng build my-lib, and then either import the built output into a local application or publish the dist/my-lib folder to npm. The steps are simple. The harder decision is whether the code deserves to be a library at all, so that comes first.
Decide whether the code should be a library
Angular defines a library as “an Angular project that differs from an application in that it cannot run on its own”. It has to be imported by an application. A library can stay inside one workspace, or it can be published as an npm package for other projects to install.
Packaging code this way is an architectural choice, not just a folder move. A library forces a boundary between reusable features and application business logic, which is the benefit. The cost is that you now design a public interface, document it, version it, and keep it compatible with the applications that depend on it. If a feature is used by only one application, a folder inside that application is usually the simpler choice. Create a library when the same feature is expected to serve several applications or teams.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesGenerate the library project
Angular’s documented starting point for a workspace that will hold libraries is a workspace with no default application:
#1 Best Overall
ng new my-workspace --no-create-application
cd my-workspace
ng generate library my-libThe CLI creates the library under projects/my-lib and registers it as a library project in angular.json. The ng generate library command also accepts the alias ng generate lib, and its generation reference documents the available options, including the public API entry file and the component selector prefix. Projects added to a workspace are placed in a projects/ subfolder by default.
You can also generate a library inside an existing application workspace. Workspace commands such as ng generate must be run from inside a workspace folder, so check your working directory first. The local setup guide covers the CLI installation these commands depend on.
Define a stable consumer API
Consumers should only ever import what the library exposes on purpose. The file that controls this is public-api.ts. Export supported components, services, and utilities through it, and do not encourage consumers to import internal files by deep path. Angular also recommends a README that covers installation and maintenance, because consumers will read it before they read your source.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →The primary entry point
Every library has one primary entry point, and its public-api.ts defines the default import path. Anything you leave out of that file is, from a consumer’s point of view, private, even if it sits in the same folder.
Secondary entry points for structured import paths
A library can also define secondary entry points, which give consumers structured paths such as my-lib/button. Each secondary entry point has its own ng-package.json and its own public API. The packager discovers these entry points during the build, so a new one needs its configuration file in place before you build.
Two rules matter here. First, import across entry points using the package import path (for example my-lib/button), never a relative path into another entry point’s source. Second, avoid circular dependencies between entry points. Entry points are built separately, and a cycle between them can make the build fail.
Rank #3
Build and consume the library locally
Build the library before an application in the same workspace imports it. The CLI adds TypeScript path mappings that point to the built library output. Those mappings should resolve to the built files rather than the source TypeScript, because the library and the application can process TypeScript differently.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchDuring development, run a watch build so the output rebuilds when you change the source:
ng build my-lib --watchLibraries are built by ng-packagr, which the Angular CLI uses for library packages. This is a separate pipeline from the one that builds applications, so do not assume that application build options or behaviour carry over to a library. Settings for one are not automatically valid for the other.
Prepare and publish to npm
For npm distribution, Angular’s library guide asks you to build with the production configuration, which produces optimized output in the package format consumers need. Publish from the generated distribution folder, not from the workspace root:
- Confirm that
public-api.tsexports only what you intend to support, and that the README describes installation and use. - Build the production package:
ng build my-lib. - Change into the output folder:
cd dist/my-lib. - Publish the package:
npm publish.
Before publishing, check the version number in the package’s configuration and make sure the name is available on your npm registry. Those are standard npm checks, and they must be satisfied before the publish step succeeds.
Free tools Windows power users keep installed
One-click scans. No signup required.
Peer dependencies and why they matter
Library packages list @angular/* packages as peer dependencies rather than regular dependencies. This means the consuming application supplies its own Angular packages, so the application and the library share one Angular module instance. Two copies of Angular in one application cause failures that are hard to trace.
Output format and Angular version compatibility
For public npm distribution, Angular recommends partial-Ivy output. Its portable format can be consumed by applications using Angular v12 or later. Full-Ivy output relies on private compiler instructions and requires the library and application to use matching Angular versions, so Angular advises against publishing it to npm.
A consuming application should use the same Angular version as the library or a newer one. The table below summarises this rule and what the documentation does not cover.
| Situation | What the documentation says |
|---|---|
| Partial-Ivy library, application on Angular v12 or later | Can consume the package (per the library guide) |
| Application uses the same Angular version as the library | Recommended |
| Application uses a newer Angular version than the library | Recommended as the stated rule: same or newer |
| Application uses an older Angular version than the library | Not stated in the library guide |
| Full-Ivy library published to npm | Advised against; requires matching Angular versions |
The Angular version guidance on this page is not dated, so confirm it against the release notes for the Angular version you are using before you set a compatibility range in your package.
Decide whether to ship schematics with the library
A library can include schematics that plug into Angular CLI commands such as ng add. This is optional. It makes sense when consumers benefit from guided setup, such as configuring a feature or adding project scaffolding during installation. The ng add reference and the library schematics guide describe how these are wired up. If your library has no setup steps, leave schematics out and keep the package smaller.
Workspace-only reuse or npm publication
Both options start with the same generated project and the same build step. They differ in who can use the output and what you take on afterwards.
Quick Recap
| Factor | Workspace-only reuse | npm publication |
|---|---|---|
| Who can consume it | Applications in the same workspace | Any project that installs the package from npm |
| Build required | Yes, ng build my-lib before local import |
Yes, the production build, then npm publish from dist/my-lib |
| Versioning and release | Not required by the workflow | Required; consumers depend on published versions |
| Angular version compatibility | Governed by the workspace | Must follow the partial-Ivy and peer-dependency rules above |
Common failures and how to check for them
- Application imports resolve to source files. Check that the TypeScript path mappings point to the built library output.
- Build fails after adding a secondary entry point. Confirm that the new entry point has its own
ng-package.jsonand public API file. - Build fails with a circular dependency between entry points. Replace relative imports with package import paths and remove the cycle.
- Consumers can reach internal code. Move the export into
public-api.tsonly if it is meant to be supported; otherwise remove it from the surface. - Two copies of Angular load in one application. Check that every
@angular/*package is a peer dependency of the library, not a regular dependency.
“
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.
