This page describes my journey of creating and publishing an NPM package and reflections about this process.
I have chosen TypeScript as a development language for the chunked-call library. Basically it’s a 3 function library with ~70 lines of code, it’s nothing special at all. My ambition was to publish something in a right way and I was positively surprised about the process and what enforced me to make it right. Please note that this page is not a guide about pushing stuff to NPM registry or how to create an NPM package project in your language of choice. For those it’s always better to see an official documentation for either NPM or for your tool/language.
Some information here might be trivial for you if you develop on daily basis in JS/TS, to me as C++ developer they weren’t.
Once I’ve managed to setup my project and deploy a package to NPM – I’ve visited proudly it’s page on the registry. My first surprise was that red button “Report vulnerability” and it feels really good that at any moment a malicious code can be reported and even those packages are getting reported by CLI npm tool during installation.
Next think was to an ability to test my lib with RunKit. I was really pleased by the UX of this page. Once I’ve tested if the lib can be imported and it works I was happy.
Mission complete, I can do something else now!
// Side note: Due an information oversaturation it’s super hard to get an updated guide for a tool to set it up. At the moment I can see that only reliable source up to date guide is the official documentation for those. Hence, I’d like to say thank you for those of you that writing and maintaining manuals.
I was jealous that other packages have nice batches. I want it also! Simple task – 5 minutes and done.
Before I close this project I took a look how it looks in the npm’s search result. There was something aside, some metrics. Wait – quality 30%?! How come?!
Search results from npmjs.com are powered by npms.io and there it’s possible to call the API page, and see which sub-metrics are taken into consideration when the quality metric is calculated.
Quality attributes are easy to calculate because they are self-contained. These are the kind of attributes that a person looks at first when checking out a package.
- Has README? Has license? Has
- Is the version stable (
> 1.x.x)? Is it deprecated?
- Has tests? What’s their coverage %? Is the build passing?
- Has outdated dependencies? Do they have vulnerabilities?
- Has custom website? Has badges?
- Are there linters configured?
I though it will be nice to have CI for sanity checks, so that I’ve configured Travis – again I was surprised how seamless is to connect a build system to GitHub project.
Also, extra batch can be added
For this release I added unit tests running by Jest + TS plugin. I have 3 public methods, hence testing those should be trivial. Interesting challenge was to gain 100% code coverage. During that process I’ve found 3 bugs, and unnecessary API what had no sense.
Why not? The same story – as somebody out of Web Development, it took me few hours to go through a pile of outdated frameworks and bootstraps. I have decided to go almost in Vanilla.
My ambition was to use the lib what I’ve published to NPM on the page, hence TypeScript for a main page code. A couple of hours and I had a working page with run-time examples. They were working fine and looked so-so.
In meantime I’ve noticed that because of using
setImmediate() function, Webpack has pulled to the bundle extra polyfill implementation for Browsers. So that I could optimize it a little bit by switching to
setTimeout(cb, 0) instead.
Page is ready, let’s test it also on Mobile. My surprise was that one of test case didn’t stop on Firefox Mobile. So that I needed to use Firefox IDE and do remote debugging. I’ve spotted problem – running out of memory. So, I’ve changed test case to make it CPU heavy, not RAM.
Page was functional, but didn’t look well on Mobile, so quickly I’ve read about
@media CSS property, and I have used Grid. Some tweaks and it works fine, and looks somehow: Demo Page.
OK! Done! Version 1.0.0 has been deployed.
Have you noticed what just happened?
Behind a funny part of collecting batches and pushing some metrics I had to:
- Write a meaningful README.md
- Configure and apply code formatter and fix linter issues.
- Create simple CI that checks commits and reports back status.
- Learn how to use a content packer.
- Configure Unit Test framework and create valuable test cases.
- Create a page what uses my library.
- Work with mobile device and remote debugging.
- Adopt the page about library to be responsive.
- Knew how to use Git and GitHub.
Touched tools / frameworks:
- Git and GitHub
- Node / NPM
And it’s only to publish 70 lines of code.
Enforcing unit testing and automation is a great engineering practice that unfortunately is undervalued by some engineers. After long time writing code I don’t trust for myself and I learned (by hard) that a code that I am most sure about can be buggy. During this I have learned something, so even is the lib will be pulled only by bots I am very happy that I have invested time to do it right.
Somehow I wish that everybody will publish at least one package to NPM Registry.