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
Have a simple design of how the library works and the contract it provides.
The usual prefixes for Angular are
ngx(Say no to ng2, ng4, ng7, etc. They seem tied to a specific version).
ngx prefixes are taken for most of the libraries of Angular, so I have used
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.
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=falsegenerates 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=scsscreates a demo app under projects, for testing your library alongside the app.
ng g library xng-breadcrumb --prefix=xngcreates a library inside the projects folder with all the necessary build and packaging steps.
git initinside the workspace to move it to a git repo, so that you can track everything from the start.
During development, run
npm linkinside the compiled project folder (./dist/library) and
npm link library-nameat the project root.
npm linksymlinks 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-
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.
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.
<breadcrumb></breadcrumb> tag at root html.
4) Auto updates library with ng update.
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
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
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.
Note: I have cross-posted this article at medium.com