AngularLibraryStarter
This is an Angular library starter built with Angular CLI.
Included are some useful changes meant to make it easier to simultaneously develop an Angular library and a GitHub-hosted demo site for that library.
- The default app in
src/app
is the demo site. It is built todocs
- making it easy to publish on Github. - There's a sample library,
@nowzoo/ngx-library-starter
, inprojects/ngx-library-starter
. - Wallaby has been set up to test the library. (You don't have to use Wallaby, though.)
Quick Start
# clone this repo into your-library-name
git clone https://github.com/nowzoo/ngx-library-starter.git your-repo-name
cd your-library-name
# install the deps...
npm i
# build the sample library...
ng build ngx-library-starter
# run the demo app
ng serve --open
Adding a real library
Generate...
ng g library your-lib --prefix your-lib
Optional step: add your NPM org namespace ...
Edit projects/your-lib/package.json
. Add the namespace to the name
field:
{
"name": "@your-org/your-lib",
"version": "0.0.1",
"peerDependencies": {
"@angular/common": "^6.0.0-rc.0 || ^6.0.0",
"@angular/core": "^6.0.0-rc.0 || ^6.0.0"
}
}
Edit tsconfig.json
in the root directory. Under compilerOptions.paths
change the keys from...
{
"paths": {
"your-lib": [
"dist/your-lib"
],
"your-lib/*": [
"dist/your-lib/*"
]
}
}
...to...
{
"paths": {
"@your-org/your-lib": [
"dist/your-lib"
],
"@your-org/your-lib/*": [
"dist/your-lib/*"
]
}
}
Optional step: add Wallaby support for the new library
Copy the library Wallaby files to the new library...
# the wallaby.js
cp projects/ngx-library-starter/wallaby.js projects/your-lib/
# the wallaby-specific tsconfig for the library...
cp projects/ngx-library-starter/tsconfig.wallaby.spec.json projects/your-lib/
# wallabyTest.ts
cp projects/ngx-library-starter/src/wallabyTest.ts projects/your-lib/src/
wallabyTest.ts
from tsconfig.lib.json
Exclude In projects/your-lib/tsconfig.lib.json
...
{
// ... other stuff...
"exclude": [
"src/test.ts",
"src/wallabyTest.ts",
"**/*.spec.ts"
]
}
- copy
projects/ngx-library-starter/wallaby.js
toprojects/your-lib/wallaby.js
- copy
projects/ngx-library-starter/tsconfig.wallaby.spec.json
toprojects/your-lib/tsconfig.wallaby.spec.json
- copy
projects/ngx-library-starter/src/wallabyTest.ts
toprojects/your-lib/src/wallabyTest.ts
- edit
projects/your-lib/tsconfig.lib.json
. Addsrc/wallabyTest.ts
toexclude
.
wallaby.js
Add an alias for the new library to the main If your demo app uses the library, you may want to add an alias in the main wallaby.js
config. In the config you pass to wallabyWebpack()
, add an entry to resolve.alias
:
var webpackPostprocessor = wallabyWebpack({
// other stuff...
resolve: {
//other stuff...
alias: {
'@nowzoo/ngx-library-starter': path.resolve(wallaby.localProjectDir, 'dist', 'ngx-library-starter'),
// add...
'your-lib': path.resolve(wallaby.localProjectDir, 'dist', 'your-lib'),
// or with an NPM org...
'@your-org/your-lib': path.resolve(wallaby.localProjectDir, 'dist', 'your-lib')
}
// other stuff
}
});
Running unit tests for the library
Angular CLI:
ng test your-lib
Wallaby: select projects/your-lib/wallaby.js
as the config file.
Running unit tests for the demo app
When unit testing the demo app remember to build the latest version of your library first:
ng build your-lib --prod
Angular CLI:
ng test your-lib
Wallaby: just select wallaby.js
in the root directory as the config file.
Publishing to NPM
Edit projects/your-lib/package.json
.
- Update the version.
- Provide a description, keywords, etc.
Build the library...
ng build your-lib --prod
Copy LICENSE
and README.md
into the distribution.
cp LICENSE README.md dist/your-lib
Publish...
# change into the distribution directory...
cd dist/your-lib
# publish...
npm publish --access public
# change back...
cd ../..
Publishing the demo app to GitHub pages
If you haven't done so already, create a repo on GitHub and update the remotes...
git remote remove origin
git remote add origin git@github.com:you/your-lib.git
Build the demo app. Make sure to set the base href to whatever the name of your repo is.
ng build --aot --prod --base-href /your-lib/
This puts the demo app into the docs
directory, ready for publishing on GitHub.
git add -A
git commit -m 'demo app built'
git push origin master
On GitHub, go to the repo's settings page. Under GitHub Pages, set the source to be Master branch docs folder.