Going down the path of node package creator - guide to create npm package and publish it to npm repository.

As I couldn’t find any Javascript package for handling Czech and Slovak National identification number, aka rodné číslo, I’ve decided to publish my own. As this was my first time going down the path of npm package maintainer, I’d like to share how it feels these days.

NVM to the rescue

Before diving into the package creation I’d like to recommend nvm, a tool for managing separate node versions/environments on your local computer. I especially like it for storing my global npm packages like yeoman or even npm itself under ~/.nvm/... directories and not under /usr/lib/node_modules which I like to keep simple and su-rights-protected.

# install nvm
nvm install node
nvm use node

Ok, nvm is installed let’s dive into package creation.

Creating package from scratch? No. Yo!

Shall I use ES5? ES6? ES7? Babel? Coffeescript? Typescript? How to configure them? What version of compiler? Why the heck are we compiling Javascript anyway? Shall I use import or require? And what’s this badge ? Automated building? Cool, how do I configure it? And how about test framework? And mocks?! Wait and what license should i choose?!

You got it. Creating a npm package is a process of overwhelming amount of decisions. Decisions someone else must’ve already undertaken. And luckily some of them shared their effort in a form of yeoman generator.

So let’s generate the package

At the time of starting my package the generator-np seemed promising, though it is a bit out of date today: . It solved most of the questions above for me. As written in the description of the generator:

Generator for npm module with ES6+, Babel, Ava, ESlint, Travis, and npm scripts

So we’ll write ES6 javascript, babel compilled, ava tested and use travis for CI. Now let’s have an empty github repo kub1x/rodnecislo cloned in rodnecislo directory and start the generator as follows:

git clone git@github.com:kub1x/rodnecislo.git
cd rodnecislo
nvm use node
npm install -g yeoman generator-np
yo np

The generator-np still asks some questions, which need to be answered. Following are my answers and the reasoning behind them.

What is the URL of your website?https://kub1x.github.io/rodnecislo/ Go to github pages, scroll under the video tutorial, click “Project page” and follow the instructions. Your url will have this form: https://your_user_name.github.io/your_repo_name/

Do you need .travis.yml?Yes. Got to Travis-ci. Create an account. Enable for your github repository. Get emails whenever you push to master something, that breaks your build, lint or tests.

Do you need setup for coveralls?Yes. You don’t need to do anything (except writing your tests…) to see beautiful visualisation of your test coverage on your coveralls page.

Do you need setup for commitizen?Yes. It feels really neat to have standardized format of commit messages. Better for cooperation, readability, confidence, automated tools… simply better. Using commitizen you basically do git cz and follow a short wizard instead of doing git commit -m “some messy message”. The resulting message looks like this: build(travis): Add node version 7 to .travis.yml. See commitizen page on how the system actually works. It defaults to angular commit standard, that is described here. Tough I find it much more helpful to get the notion from the actual commit messages in the angular repo.

Do you need automatic github releases?Yes. This gives us a great benefit of generated releases. The tool for it, conventional-github-releaser, tells you exactly what to do to, which itself helps so much, that I can’t resist repeating it here (just a little more specific). Going from version 0.0.1 to 0.0.2:

1. Make a change
2. npm run verify
3. git cz the change
4. Make sure Travis CI turns green
5. Repeat until enough changes to call it a version ;P
6. Do npm login with your npmjs.org account. I failed to do this and accidentally published my package as a wrong user ;)
7. npm run major OR minor OR patch - does all the following for you:
   • Run tests, verifications, etc.
   • Bump version in package.json, commit, create git tag and push it
   • npm publish to npmjs repo
8. npm run github-release - creates the nice release report on github mentioned earlier
9. Celebrate… and maintain.

Do you need CLI?No. As I’m writing npm library rather than console tool, I don’t expect it being used from command line. But for the sake of completeness the cli option of the generator creates this file in your package’s src directory and adds meow to your deps. That’s it.

Aaaand we’re done… Almost

After the generation process finishes the whole project is automatically being set up. The template itself takes care of npm install, running your first build, lint, tests, and checking for outdated dependencies using npm outdated. I recommend reading the output of the generation process as there is practically everything you need to know about your newly generated package, especially the npm scripts being called. At the time of writing, some of the packages are outdated downright after the generation due to inactivity of the maintainer (perhaps someone could offer him a hand ;)). To fix this use npm-check-updates tool:

npm install -g npm-check-updates
ncu -a

Now this is just the beginning. Even the first version of the module took quite some time on research, programming and writing. I’m kinda wondering how maintaining of it will go, so about it later.

Cheers, npm install rodnecislo and go opensource.