Top 5 things to consider when creating an Angular library

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 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. (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.

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 to showcase library usage-

✅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.

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 and Library creation.

✅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 and demo app is hosted on Netlify.

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.

Check the Git repo, 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 or Twitter

Note: I have cross-posted this article at medium.com