Lets you focus on the stuff that matters

@ngneat/lib

Schematics that wrap the Angular generate library schematics and provide all the standard boilerplate you need in order to create a neat Angular open-source project.

ng add @ngneat/lib @scope/toaster # change @scope/toaster with your lib name

Features

👆 Only Single command to do everything
📂 A schematic carrying scaffolding for Angular Library
📄 Contains community documents and templates which enhances open-source experiences with GitHub
📦 Semantic release support
⚡ GitHub Actions workflows
🚀 Site Deployment with angular-cli-ghpages
🧑‍🤝‍🧑 Adds All-Contributors specifications
🔐 Sets up Commitlint, husky, prettier and lint-staged
📜 Configures all needed scripts in package.json
🐬 Works with NX workspace
✨ Lints newly created library project

Table of Content

Version
Usage
Development, release and deployment flow
Files
Scripts
- Root package.json
- Library package.json
Hooks
Extras
Badge
Contributors ✨

Version

Angular	@ngneat/lib
v14	5.x.x
v13	4.x.x
v12	3.x.x
v11	2.x.x

Usage

Create library with schematics

ng add @ngneat/lib @scope/toaster # change @scope/toaster with your lib name

Generate schematics in existing library

ng generate @ngneat/lib:create-schematics @scope/toaster # change @scope/toaster with your lib name

Options

Name	Type	Description
`name`	`string`	The name of the library. Valid examples: `toaster`, `@scope/toaster` Default: `argv[0]`
`scope`	`string`	The npm scope of the library. Not needed if you are providing scope in `name` itself
`ci`	`enum["github-actions", "travis", "circle"]`	Determine which CI tool to use. Default: `github-actions`
`repositoryUrl`	`string`	The repository URL
`skipLib`	`boolean`	When true, will not create the library. Useful when you only want to add schematics in your existing library
`entryFile`	`string`	The path at which to create the library's public API file, relative to the workspace root. Default: `public-api`
`prefix`, `p`	`string`	A prefix to apply to generated selectors. Default: `lib`
`skipPackageJson`	`boolean`	When true, does not add dependencies to the "package.json" file. Default: `false`
`skipInstall`	`boolean`	When true, does not install dependency packages. Default: `false`
`skipTsConfig`	`boolean`	When true, does not update "tsconfig.json" to add a path mapping for the new library. The path mapping is needed to use the library in an app, but can be disabled here to simplify development. Default: `false`
`skipSchematics`	`boolean`	When true, does not set schematics to support "ng add ..." command Default: `false`
`skipAngularCliGhPages`	`boolean`	When true, skips setting angular-cli-ghpages configurations Default: `false`
`botName`	`string`	This name will be used while deploying on GitHub Pages
`botEmail`	`string`	This email will be used while deploying on GitHub Pages
`cocEmail`	`string`	his email will be used in Code of Conduct
`skipSpectator`	`boolean`	When true, does not add `@ngneat/spectator` Default: false

Development, release and deployment flow

This is very opinionated flow based on semantic-release release workflow, you can choose to have your own flow!

Library Development

Initial setup

Create a new project with Angular CLI:

npm i -g @angular/cli
ng new toaster # change toaster with your lib name
cd toaster

Create a fully-featured library project with @ngneat/lib:

ng add @ngneat/lib @scope/toaster

Answer the prompts and you will then have your library ready!

Running the library locally

Once you're done with creation of library, you can now start writing actual code for the same.

After adding minimal features, you will want to run and test your library in local environment, below is how you do it:

Import ToastModule from @scope/toast in your app.module.ts
Make necessary changes to run your library
Run the default project using ng serve
And test your library!

Schematics Development

@ngneat/lib not only helps you to create an Angular library, but it also comes with a basic ng add schematics! So that you don't have to worry about setting up schematics from scratch.

Schematics for your library are present at /projects/scope/toaster/schematics. Everything is configured there, so can simply test it and make changes as needed.

Running schematics locally

To run and test schematics, you can follow below steps:

Run npm run build:lib
Go to library dist folder: cd dist/scope/toaster
Pack the library using npm: npm pack and it will create a .tgz file
Open the new terminal and go to another Angular project where you want to test
Run ng add /path/to/.tgz/file in new terminal

Change `base-href` for deployment

Make sure to change --base-href in deploy script of package.json.

{
  "scripts": {
    "deploy": "ng deploy --base-href=https://username.github.io/repo/",
  },
}

Commit messages

Apart from library and schematics setup, @ngneat/lib helps you to follow conventional-changelog by adding all the needed setup.

Simply run npm run commit each time you when you commit. And answer the prompts to get a formatted commit messages.

Releases

Automated releases with GitHub Actions

@ngneat/lib adds a workflow called release.yml to make you release fully automated. You simply need to keep pushing using formatted commit messages and rest will be taken care!

Workflow	Runs On	Tasks
`release.yml`	✔️ All Branches	✔️ Lint ✔️ Build ✔️ Test ✔️ Versioning based on the Semantic Versioning specification. ✔️ Publish library on specific channel ✔️ Make release tag on GitHub ✔️ Adds `released@channel` label and friendly comments on issues

Secrets and tokens

You will need to create NPM_TOKEN and GH_TOKEN tokens for semantic-release and angular-cli-ghpages to work perfectly. Read more here .

Initial release

Let's start by making the first commit with message: feat: initial commit. When pushing this commit, on master branch, semantics-release will release the version 1.0.0 and users can use it from the default distribution channel, i.e. the dist-tag @latest for npm.

So, up-to now, Git history looks like this:

* feat: initial commit # => v1.0.0 on @latest

Working on a future release

We now want to work on a future major release, which can have multiple features, some of them will be breaking changes. But, before making it available to our users, we want to make sure that all the features are developed and tested. And we also do not want to increment our package version.

For above, we can create the branch beta (name can be alpha, beta, next, next-major, but only alpha and beta support pre-releasing in default semantic-release configuration) and commit the first feature there. Once pushed, semantic-release will publish the pre-release version 2.0.0-beta.1 on the dist-tag @beta. This helps us to run tests by installing the library with npm install libName@beta or ng add libName@beta. Other users installing with npm install libName or ng add libName will sill receive the version 1.0.0.

The Git history of the repository is now:

* feat: initial commit # => v1.0.0 on @latest
| \
|  * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta

We can continue to work on our future release by committing and pushing other features or bug fixes on the beta branch. With each push, semantic-release will publish a new pre-release on the dist-tag @beta, which allow us to run our integration tests.

With another feature, the Git history of the repository is now:

* feat: initial commit # => v1.0.0 on @latest
| \
|  * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
|  * feat: second feature # => v2.0.0-beta.2 on @beta

For more in-depth guide to release workflow, visit semantic-release

Deployment

Automated deployment using GitHub Actions

@ngneat/lib has also added angular-cli-ghpages for deployment. There is one more workflow added called: deploy.yml:

Workflow	Runs On	Tasks
`deploy.yml`	✔️ `master`	✔️ Build ✔️ Deploy on GitHub Pages

Manual deployment

You can simply run npm run deploy to deploy your default project on GitHub pages. But, automated way is recommended over this.

Summary

To summarize with steps, below is what all you need to do:

Create new project using Angular CLI
Create library in it using ng add @ngneat/lib @scope/libName
Change --base-href of deploy script in root package.json
Develop your library
Write specs
Test your code in the project itself
Run npm run test:lib
Run npm run build:lib
Test the schematics
Run npm run commit
Push
Let GitHub Actions finish running tests and releases
And you're done with first release!
Make new branch (name can be alpha, beta, next, next-major)
Repeat steps 4 to 12
Install and test your library from distribution channels, e.g. npm install @scope/libName@beta or with schematics: ng add @scope/libName@beta
Once tested, merge with master
Again, let GitHub Actions finish running tests and releases
And you're done with next release!

Files

Several files were created. Let's go over them:

- projects/
-   scope/
-     lib/
-       schematics/ # contains files for *ng add libName* support
-       src/ # contains lib source file
- .releaserc.json
- CODE_OF_CONDUCT.md
- commitlint.config.js
- CONTRIBUTING.md
- ISSUE_TEMPLATE.md
- LICENSE
- PULL_REQUEST_TEMPLATE.md
- README.md

Scripts

Root package.json

build:lib - Builds the library and copies root README.md file to lib in dist folder
postbuild:lib - Runs build command from lib's package.json
commit - Creates a new commit message based on Angular commit message convention
contributors:add - Adds a new contributor to the README file
deploy - Deploys site to GitHub pages
semantic-release - Runs semantic-release, should be run through CI
test:lib - Runs tests
test:lib:headless - Runs tests in headless mode with Chrome

Library package.json

build - Builds schematics
postbuild - Runs below scripts once build is done
copy:schemas - Copies schematics files to lib in dist folder
copy:collection - Copies schematics/collection.json to schematics in dist folder

Hooks

pre-commit: Runs prettier on the staged files, and verifies that they don't contain debugger, fit, or fdescribe
pre-push: Runs the test:lib:headless command

Extras

Running the add command updates the tsconfig.json file so that you can import any files from the npm path (@scope/name) rather than from relative paths.
It also populates the library's package.json with the initial required information. Make sure you verify the data is accurate before proceeding.

Badge

Show that your project is based off of our lib

[![ngneat-lib](https://img.shields.io/badge/made%20with-%40ngneat%2Flib-ad1fe3?logo=angular)](https://github.com/ngneat/lib)

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{Itay Oded}

_{Netanel Basal}

_{Steven Harris}

_{Dharmen Shah}

This project follows the all-contributors specification. Contributions of any kind welcome!

ngneat/lib