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) andnpm 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
Top comments (0)