🤖 Lets you focus on the stuff that matters
Lets you focus on the stuff that matters
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
Angular | @ngneat/lib |
---|---|
v14 | 5.x.x |
v13 | 4.x.x |
v12 | 3.x.x |
v11 | 2.x.x |
ng add @ngneat/lib @scope/toaster # change @scope/toaster with your lib name
ng generate @ngneat/lib:create-schematics @scope/toaster # change @scope/toaster with your lib name
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 |
This is very opinionated flow based on semantic-release release workflow, you can choose to have your own flow!
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!
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:
ToastModule
from @scope/toast
in your app.module.ts
ng serve
@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.
To run and test schematics, you can follow below steps:
npm run build:lib
cd dist/scope/toaster
npm pack
and it will create a .tgz
fileng add /path/to/.tgz/file
in new terminalbase-href
for deploymentMake sure to change --base-href
in deploy
script of package.json
.
{
"scripts": {
"deploy": "ng deploy --base-href=https://username.github.io/repo/",
},
}
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.
@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 |
You will need to create NPM_TOKEN
and GH_TOKEN
tokens for semantic-release
and angular-cli-ghpages
to work perfectly. Read more here .
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
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
@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 |
You can simply run npm run deploy
to deploy your default project on GitHub pages. But, automated way is recommended over this.
To summarize with steps, below is what all you need to do:
ng add @ngneat/lib @scope/libName
--base-href
of deploy
script in root package.json
npm run test:lib
npm run build:lib
npm run commit
alpha
, beta
, next
, next-major
)npm install @scope/libName@beta
or with schematics: ng add @scope/libName@beta
master
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
build:lib
- Builds the library and copies root README.md file to lib in dist folderpostbuild:lib
- Runs build command from lib's package.jsoncommit
- Creates a new commit message based on Angular commit message conventioncontributors:add
- Adds a new contributor to the README
filedeploy
- Deploys site to GitHub pagessemantic-release
- Runs semantic-release, should be run through CItest:lib
- Runs teststest:lib:headless
- Runs tests in headless mode with Chromebuild
- Builds schematicspostbuild
- Runs below scripts once build is donecopy:schemas
- Copies schematics files to lib in dist foldercopy:collection
- Copies schematics/collection.json to schematics in dist folderpre-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
commandRunning 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.
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)
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!