Creating an npm package

Creating an npm package

Most of my Node.js projects require some build routine. As a fan of minimalism, for simple builds I used to write short scripts operating directly on fs. In order to avoid duplication and simplify the process for future, I created a simple npm package. I described the required steps below.

Repository, License, Readme

I created a new GitHub repository and added a license and readme files to it. I chose a permissive license MIT to allow broad usage. Then I cloned the repository in my machine.

Package.json

Next, I initiated an npm project:

Shell

After answering a couple of questions, package.json was created.

Source code

The obvious and omitted here thing was the essence of the package – source code. For the purpose of this article let’s assume it’s a single index.js file. I put the name as the main file in package.json:

JSON
package.json

I also added some tests to the project and filled in the test script:

JSON
package.json

Automatic builds

I wanted to have the project automatically built and unit tests executed, so I used Travis CI. It will build my project every time I push a new commit to it.

I created an account by logging with my GitHub account and enabled support for my project by going to Settings > Repositories. I also needed to add one file to my project – .travis.yml:

Plain Text
.travis.yml

This file says that my project is built in Node.js and I want to build and run tests in three environments: Node.js v8, v9, and v10.

Badges

You have probably seen different badges in GitHub projects, stating the last version, the status of the build, code quality and coverage, and so on. I added a few to my project as well.

Most of the badges are created by putting a line to the README.md file:

Plain Text

In some cases it will be enough to change the account and repository names in the snippets below to use them for a new project, but some will require creating an account in the appropriate service.

Badge: build status

I used Travis CI‘s badge that says whether current code is compiling and passes tests:

Plain Text
README.md

As stated before, I had to have the account in Travis CI.

It will display the last published version and provide a link to the npm package:

Plain Text
README.md

I will mention publishing to npm later.

Badge: status of dependencies

badge

It will display the status of npm packages used by my project:

Plain Text
README.md

Badge: license

It will display the license of my project:

Plain Text
README.md

It will show the project’s license name (from npm) and link to the LICENSE file.

Badge: test coverage

Coverage Status

It will display the code coverage by tests:

Plain Text
README.md

Note: the Coveralls service requires access to all your repositories, including private.

More badges

There are many more badges available, e.g. number of weekly downloads, license scan, link to glitter, amount of sponsors, code style and maintainability, and so on. Most of the badges can be found in Shields IO service.

Publish to npm

Before publishing a package, I had to create an account in npm. A strange thing, the email I provided will be publicly available. There were discussions about this issue, like #16, and the problem is still present.

Next, I logged in to the service by running:

Shell

I published the first version to npm by typing:

Shell

There are also available commands to update the version of my package:

Shell

All details can be found in the documentation, but the effect of this command is:

  • updating the version in package.json and package-lock.json
  • commit the changes to git
  • create a git tag with the version
  • publish to npm

It is also possible to provide custom commit message by appending -m "Upgraded to %s", where %s will be replaced with the new version.

Remember to push the tags along the commits:

Shell

Leave a Reply

avatar
  Subscribe  
Notify of