Top 5 things to consider when creating an Angular library
Tags: javascript, angular, webdev, beginners
Published: 2019-06-26 17:56:18

---
title: Top 5 things to consider when creating an Angular library
published: true
description: Essential checklist and best practices for beginners in creating and releasing your first Angular library
canonical_url: https://medium.com/@udayvunnam/https-medium-com-udayvunnam-be-the-thanos-of-your-angular-library-320f93ddc9ec
tags: javascript, Angular, webdev, beginner
cover_image: https://thepracticaldev.s3.amazonaws.com/i/spw9cfkhqtggq4t8rmm1.png
---

> Essential checklist and best practices for beginners in creating and releasing your first Angular library

If you are planning to create a library, don't wait. The time is now. The current open source tools make everything so seamless. Below are the steps I followed to release my first library. As we go along, you can check the [GitHub repo](https://github.com/udayvunnam/xng-breadcrumb) for reference.

- Plan your library
- Setup Angular workspace for library and it's demo app
- Empathize with your users and fellow developers
- Configure CICD
- Announce it to the world



# ✅Plan your Library

Have a simple design of how the library works and the contract it provides.

The usual prefixes for Angular are `ng` or `ngx`(Say no to ng2, ng4, ng7, etc. They seem tied to a specific version). `ng` and `ngx` prefixes are taken for most of the libraries of Angular, so I have used `xng` prefix. 

After choosing the name of your library, create a simple folder with package.json and publish it to npm under your account. Follow the [guide to publish npm packages with basic setup](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages). (This ensures package name is available and your ownership of it).  You can even use scoped packages @scope/package-name if the regular package name of your wish isn't available.

Try to create a unique library that can do any of the following

- makes a particular task easy 
- provides a configurable solution
- tweaks a functionality
- offers a visual UI component
- simplifies a process

Library API design - The right things have to be the defaults of your library. We don't need the user specifying the redundant configuration, which otherwise is a default.

 
I have planned xng-breadcrumb with the following API design -

1) Add breadcrumb selector in html, wherever the user wants to show breadcrumbs.

2) Show default breadcrumb same as the path, if no configuration is provided. The user just needs to add `<breadcrumb></breadcrumb>` for a quick start.

3) Declarative: Add a custom label to a route by directly defining it in route configuration of App.

4) Dynamic: provide a service to update a route label lazily. Ex: In product details page we show product id in URL but want to show product name in the breadcrumb, which is fetched asynchronously from a server.

5) Skip specific path from displaying in the breadcrumb. Come path even though it appears in URL has no meaning in the breadcrumb. We have to provide a way to hide it.

Start with releasing useful features first and iterate from user feedback and feature requests.



# ✅Setup Angular library and a demo app

With Angular CLI you are just a few commands away from setting up a library and a demo app. You can test your library usage along with the demo app. Thanks to Angular CLI 😍.

You have already chosen a unique name for your library. For me, it is `xng-breadcrumb`. Below are the basic commands for initiating an Angular workspace with a library and its demo app.


```javascript
1) ng new xng-breadcrumb --createApplication=false
2) ng g application xng-breadcrumb-app --style=scss
3) ng g library xng-breadcrumb --prefix=xng
4) git init
5) npm link ./dist/xng-breadcrumb && npm link xng-breadcrumb
```

- `ng new xng-breadcrumb --createApplication=false` generates a blank Angular workspace. If createApplication is not false, the unique library name is actually applied to demo app and later you would need to rename it in angular.json. To avoid this just start as above. We can create both the library and demo apps under the projects folder in the next steps.

- `ng g application xng-breadcrumb-app --style=scss` creates a demo app under projects, for testing your library alongside the app.

- `ng g library xng-breadcrumb --prefix=xng` creates a library inside the projects folder with all the necessary build and packaging steps.

- `git init` inside the workspace to move it to a git repo, so that you can track everything from the start.

- During development, run `npm link` inside the compiled project folder (./dist/library) and `npm link library-name` at the project root. `npm link` symlinks compiled package folder to the npm package and any changes you make to the library reflects immediately in the demo app.


xng-breadcrumb's [demo app](https://xng-breadcrumb.netlify.com) to showcase library usage-

![](https://user-images.githubusercontent.com/20707504/60205896-0211f080-9870-11e9-9b14-9a3382945c64.gif)

# ✅Empathize with your users and fellow developers

No matter how great your library is, people, won't use it unless you provide good documentation so, provide a README with -

- _Quick Start_ - The simplest way possible to use your library. Make it as easy as it can be to start with your library.

- _Usage and API_ -library API,  features and common patterns of doing usual things should be documented. Good documentation can save a lot of time for users. They don't have to dig deep into the code or choose an additional library or implement a custom solution when its already offered with the library.

- _Demo URL_  - provide a playground of your working library within an App.

- _Development guide_, _Contribution guidelines_ will look welcoming for other developers to contribute.

- _Badges_ - Add badges to show deployment status, test status, release version, and other repo activities

A clear license gives the confidence to use your library. MIT is the defacto standard for opensource. To know the importance of licensing read [React's license change from its own custom license to MIT after developer backlash](https://thenextweb.com/dd/2017/09/25/facebook-re-licenses-react-mit-license-developer-backlash/).


##Schematics

Provide Schematics to the library(specific to Angular). Users can easily use `ng add` to include a base version of your library into their project.

`xng-breadcrumb` schematic on `ng add` will do the following.

1) Installs and adds the library to package.json

2) Imports the `BreadcrumbModule` to root Module.

3) Places `<breadcrumb></breadcrumb>` tag at root html.

4) Auto updates library with ng update.

There is already great documentation from Angular on [Schematic authoring](https://angular.io/guide/schematics-authoring) and [Library creation](https://angular.io/guide/creating-libraries).



# ✅Configure CICD

CICD is the norm of software development. Automate everything -linting, build, tests, publishing to npm and demo app deployment. You only have to set it up once to make life easier. Test your code but not the users :)

- *Prettier* and *Husky* for linting automatically on git commit

- *CircleCI* or *Travis* for configuring CICD

- *Netlify* for hosting demo App

xng-breadcrumb is configured with below steps using [CircleCI](https://github.com/udayvunnam/xng-breadcrumb/blob/master/.circleci/config.yml) and demo app is hosted on [Netlify](https://xng-breadcrumb.netlify.com).

1) *build* and *test* every commit of every branch.

2) *deploy* demo app(`netlify deploy`) only if the code is pushed or PR is merged to the master branch. build and tests should succeed to deploy.

3) *publish* to npm(`npm publish`), whenever a new release is tagged in the repo using `git tag vX.Y.Z`



# ✅Announce it to the world

You have put in a lot of effort. Now it's time to showcase it to the world for use. Announce it on LinkedIn, Twitter, Reddit and any platform with your target audience.

Be open about contributions, bug fixes, and feature requests.

Once your library is found useful and attains enough users, Google takes care of rest.


***

If you plan to add breadcrumbs to your Angular project, try [xng-breadcrumb](https://github.com/udayvunnam/xng-breadcrumb). 

Check the [Git repo](https://github.com/udayvunnam/xng-breadcrumb), if you wish to create an Angular library with complete setup. Contributions, issues, and feature requests are welcome.

Anything you would like to let me know? connect via [LinkedIn](https://www.linkedin.com/in/udayvunnam/) or [Twitter](https://twitter.com/codeasync)

Note: I have cross-posted this article at [medium.com](https://medium.com/@udayvunnam/https-medium-com-udayvunnam-be-the-thanos-of-your-angular-library-320f93ddc9ec)