My First NPM Package
Written by Hunter Jansen on July 19, 2016
Today I’m going to talk a little bit about something that I’ve been spending the (very few) extra moments of my time with over the last couple of weeks - creating an Angular 2 plugin to be consumed as an NPM package.
When we started bringing ICUC’s main product over from a MASSIVE Angular 1.x app to an angular 2 app, we knew that we would have issues finding plugins that functioned similarly to the ones we’ve been using in our existing application. Heck, at the point of writing this, Angular 2 isn’t even released yet (it’s currently in rc.5). There are very few options for giant frameworks like bootstrap, and considerably fewer options out there for more mundane stuff that has been created to work with Angular 1.x.
One such case is a robust selection tool allowing for multi-selection, ordering/selecting by ‘groups’, and in general just a very robust multi-select plug in.
Multi-select is something that we use heavily in our Angular 1.x app, so to consider the notion of redefining our workflows to not include this idea is just something that wouldn’t be worth the workflow design cycles. Not to mention, the ability to select multiple items from a list, ordered by groups, is just something that makes sense - not just for us, but I’m sure in many other places.
And so enters ng2-group-multiselect - an Angular 2 plugin that takes those ideas and provides a component to provide that functionality, while being flexible enough to just act as an Angular 2 select item. At the time of writing this, it’s still in a v0.0.4 release, so definitely not ready for prime time - but it’s already got the base of what we at ICUC were looking for from a multi-select component.
Getting this far was interesting
Something that I personally value in an Angular 2 plugin is excellent documentation, the fact that it’s been thoroughly tested, is open source, contains demos on how to use it, and is readable in its implementation. So I tried to keep all of those principals in mind when starting this plug in.
That means that I started with a lot more than I needed. In order to power my demo page, I needed Angular 2 included, webpack to build it and all the loaders associated with that, AND asome server logic for live reload. that’s a considerable amount of overhead, for something that ends up being maybe 100 lines of non-minified code.
I started with creating my component logic and the demo page. While I was confident that I could just go ahead with creating the LOGIC at least for the component I knew that it would make just as much sense to build out my demo page while I built the component to test the functionality and build the demo page out at the same time. This allowed for quick iterations through what will be the final shipped project, but also ensures that the additional task of providing a demo is already largely taken care of due to the fact that I made my own demo as I went along.
Adding a package to NPM is ridiculously easy
It’s surprising just how simple it is. All you REALLY need is an NPM account and a package.json in your project. If you’re building anything complicated or, are including a demo page with your package like I’m doing, you already have a package.json. So all need to do is register as a user for NPM. The instructions for that, and really every thing to do with registering a package can be found on the NPM page.
So all you have to do, after you’ve added your user, is be in your project’s root directory and run the command:
It’s really that easy.
I was very excited and googled ‘npm mypackagename’ and found it was already on a few sites. DANG!
But did it work? The main way I could think of to test this was to leave my project, cd into a new directory and run:
npm install <myPackage>
And holy jeez, it worked. It installed stuff. MY stuff. FROM THE INTERNET
If you’re anything like me, you published too soon
I published my 0.0.1 version when things were still very broken; I had ( and still do, lol ) significant amount of bugs in my code, there was no easy way to include my module, my tests aren’t in place, styling’s not done, I don’t have a demo site, my README wasn’t fleshed out, etc. etc. etc.
Heck, my repo was even still private; that seems a little rude. My favourite part about using github and plugins hosted on there is reading the sourcecode that others contribute.
This is where I really like NPM’s versioning updates; once again it’s dead simple.
I started by updating my README with some documentation and a big disclaimer letting people know this isn’t ready for prime time; but I need to publish this out, so that people don’t have my outdated code. I need to update my NPM package. NPM follows the notions of Major.Minor.Patch changes. I don’t even need to manually update my package.json, npm takes care of it for me when I tell it that I’m ready to update my package.
All I had to do was commit my changes locally, and run:
npm version patch
My version number for my new package was updated from 0.0.1 to 0.0.2, awesome - that’s exactly what I needed. Following that, all that’s required is another publish command and everywhere is updated with the new version of the package. Dead. Simple.
And . . . That’s essentially where I’m at right now. I’m actually a little bit further, but this post is a little long as it is, so I’ll save my next steps for later.
Next Time I’ll quickly go over setting up my package’s demo page to work with github pages, and making my new domain play nicely with github pages.
Talk soon! -Hunter