top

0 to npm module, how to publish your open source code

In this article, we are going to explore how to publish our open source (OS) code into the npm registry as a module. npm is currently the largest software repository in the world with over 600 thousand modules published (As of January 2018). It’s used to publish from very small modules (1 line functions) to complete frameworks (like React) and even full P2P clients (like WebTorrent). Introduction Before we continue, this is the list of things we should have beforehand: Node.js and npm installed (LTS recommended) GitHub account An IDE (I’ll be using WebStorm), a few options: Atom Visual Studio Code WebStorm (Free for OS & Education) Terminal (I’ll be using iTerm with zsh in MacOS) 1. Creating an npmjs.com account Our first step is to create an npm account. Now, there are two ways of doing that. The first is through the website and the second is through using npm’s CLI (which you should have installed already) with the command adduser. If you had already created your user or you just did through the website, you must now use npm login in the terminal to store your credentials. adduser command should have stored the credentials automatically (login is just an alias) To test what we just did, type npm whoami to ensure that our credentials were stored. 2. Creating our project Our first step is to create an new GitHub repository, for this tutorial I will be publishing a simple module which wraps async functions with debug (a logger) logging for express (a web framework). I’ll call it express-debug-async-wrap for now. But is it available in the public scope? Just search it or go directly to the package. If you searched for a simple word, there’s a chance a module that has it in its name or in its keywords and will show up, even then, your package name might be free to take. The safe your is to go directly with this url expression: https://www.npmjs.com/package/<package name here> Great, we can proceed with the name express-debug-async-wrap in mind. Note that we can use any name under our personal scope @username/my-package even if it’s already taken in the public scope. Naming our modules is an important thing. Recently, npm updated it’s naming rules to prevent name hijacking. You can read more about it in this blog post. We can use A-Z, a-z, 0-9 and punctuations like dots, dashes, and underscores. Creating the GitHub repository With our name in mind, we continue to create the GitHub repository. On GitHub go to the top right corner and click the “+“ with an arrow by its side: We add our project’s name and description. Select “Initialize this project with a README”. And finally, we add Node’s .gitignore and MIT License. You are free to select the license that best suits you. Learn more here Once we click on “Create repository”, we should have the following: 3. Adding our code Cloning the GitHub Repository To add our code we must first clone the GitHub repository in our machine. To do so, we must click on “Clone or download” green button in our repo and copy the url: Next, we must clone the repository in our machine using git: Initializing the npm package Once we have the repository, we should “get into” it and initialize the directory with a package.json, to do so, we use npm init and fill the blanks: Version should start in 1.0.0 unless we are doing alpha/beta release Default entry point index.js works for our this first case, but keep in mind if the entry point is different, maybe in lib/ or dist/ Test command is completely up to you, I use and recommend standard code style for linting, ava for tests for nyc for code coverage. (These must be installed with as dev dependencies) Leave git as default, it should be the GitHub repo we just created. Add as much relevant tags as needed Match the license chosen in the repo The package.json contents will be shown and the CLI tool will ask for confirmation: Our directory should look like this in our IDE: package.json is in red (Under WebStorm) because is untracked by git Creating index.js We now continue with the important part, the code, in a new file called index.js: We must use exports or the real deal: module.exports. We can export anything: a function, an object, an array, a class, a string, etc.  Note: To learn the difference between exports and module.exports we can read more here. Committing our files to git Last, but not least, we must add our files to our git repository. A quick git status shows us the following: We can see the recently created package.json and index.js. In my case, because I’m using WebStorm, I also see a .idea folder, which is appended to the .gitignore file to be ignored. Once we’ve ignored the unnecessary files, we add everything and commit: 4. Publishing our module Although our npm modules don’t have to live in a public repository, I personally think they should, and they should match whatever is stored in the npm registry. So we tag this first version (new releases should be done with npm version which automatically tags them), push to GitHub, push tags and finally publish to npm: That’s it! Our module lives in the npm registry. 5. Completing our README Our module can be used by anyone, but sadly, the page for it looks like this: It’s empty and sad, no explanation on how to use it, nothing. We should definitely add a few things: basic badges, how to install, how to use, related packages and a footer stating our copyright and the license. For our module it looks like this: # express-debug-async-wrap [![npm](https://img.shields.io/npm/v/express-debug-async-wrap.svg?style=flat-square)]() [![npm](https://img.shields.io/npm/dm/express-debug-async-wrap.svg?style=flat-square)]() [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg?style=flat-square)](https://standardjs.com) [![npm](https://img.shields.io/npm/l/express-route-autoloader.svg?style=flat-square)](LICENSE) express async wrapper that passes custom debug instance and returns 400 as default error code ## Install ``` npm i -S express-debug-async-wrap or npm install --save express-debug-async-wrap ``` ## Use Require and initialize with `debug` instance: ```js const debug = require('debug')('backend:routes:doc') const wrapper = require(`express-debug-async-wrap`)(debug) const express = require('express') const router = express.Router() router.get('/', wrapper(async (req, res) => {   await ...   await ...   res.send('OK') })) module.exports = router ``` ## Related - [express-route-autoloader](https://github.com/DiegoRBaquero/express-route-autoloader) - [sequelize-express-findbyid](https://github.com/DiegoRBaquero/sequelize-express-findbyid) ## License MIT Copyright © [Diego Rodríguez Baquero](https://diegorbaquero.com) Once it’s done, we must create a patch version, push to GitHub and publish to npm. After committing our changes: That’s it! 6. Final touches and homework Important: Add tests and setup CI! (Travis recommended) Add more badges: travis build, security related, etc. Here’s an example: Share your module in social media, forums, IRC/Gitter channels Tell me how you did and share me your module. Learn more about npm
Rated 4.0/5 based on 0 customer reviews
Normal Mode Dark Mode

0 to npm module, how to publish your open source code

Diego RBaquero
Blog
08th Feb, 2018
0 to npm module, how to publish your open source code

In this article, we are going to explore how to publish our open source (OS) code into the npm registry as a module.

npm is currently the largest software repository in the world with over 600 thousand modules published (As of January 2018). It’s used to publish from very small modules (1 line functions) to complete frameworks (like React) and even full P2P clients (like WebTorrent).

Introduction

Before we continue, this is the list of things we should have beforehand:

1. Creating an npmjs.com account

Our first step is to create an npm account. Now, there are two ways of doing that. The first is through the website and the second is through using npm’s CLI (which you should have installed already) with the command adduser.

If you had already created your user or you just did through the website, you must now use npm login in the terminal to store your credentials. adduser command should have stored the credentials automatically (login is just an alias)

To test what we just did, type npm whoami to ensure that our credentials were stored.

2. Creating our project

Our first step is to create an new GitHub repository, for this tutorial I will be publishing a simple module which wraps async functions with debug (a logger) logging for express (a web framework). I’ll call it express-debug-async-wrap for now. But is it available in the public scope? Just search it or go directly to the package.

Creating our project

If you searched for a simple word, there’s a chance a module that has it in its name or in its keywords and will show up, even then, your package name might be free to take. The safe your is to go directly with this url expression: https://www.npmjs.com/package/<package name here>

Great, we can proceed with the name express-debug-async-wrap in mind. Note that we can use any name under our personal scope @username/my-package even if it’s already taken in the public scope.

Naming our modules is an important thing. Recently, npm updated it’s naming rules to prevent name hijacking. You can read more about it in this blog post. We can use A-Z, a-z, 0-9 and punctuations like dots, dashes, and underscores.

Creating the GitHub repository

With our name in mind, we continue to create the GitHub repository. On GitHub go to the top right corner and click the “+“ with an arrow by its side:
Creating the GitHub repository

We add our project’s name and description. Select “Initialize this project with a README”. And finally, we add Node’s .gitignore and MIT License.

You are free to select the license that best suits you. Learn more here

Once we click on “Create repository”, we should have the following:

3. Adding our code

Cloning the GitHub Repository

To add our code we must first clone the GitHub repository in our machine. To do so, we must click on “Clone or download” green button in our repo and copy the url:

Next, we must clone the repository in our machine using git:

Initializing the npm package

Once we have the repository, we should “get into” it and initialize the directory with a package.json, to do so, we use npm init and fill the blanks:

  • Version should start in 1.0.0 unless we are doing alpha/beta release

  • Default entry point index.js works for our this first case, but keep in mind if the entry point is different, maybe in lib/ or dist/

  • Test command is completely up to you, I use and recommend standard code style for linting, ava for tests for nyc for code coverage. (These must be installed with as dev dependencies)

  • Leave git as default, it should be the GitHub repo we just created.

  • Add as much relevant tags as needed

  • Match the license chosen in the repo

The package.json contents will be shown and the CLI tool will ask for confirmation:

Our directory should look like this in our IDE:

package.json is in red (Under WebStorm) because is untracked by git

Creating index.js

We now continue with the important part, the code, in a new file called index.js:

We must use exports or the real deal: module.exports. We can export anything: a function, an object, an array, a class, a string, etc. 

Note: To learn the difference between exports and module.exports we can read more here.

Committing our files to git

Last, but not least, we must add our files to our git repository. A quick git status shows us the following:
Creating index.js

We can see the recently created package.json and index.js. In my case, because I’m using WebStorm, I also see a .idea folder, which is appended to the .gitignore file to be ignored. Once we’ve ignored the unnecessary files, we add everything and commit:

4. Publishing our module

Although our npm modules don’t have to live in a public repository, I personally think they should, and they should match whatever is stored in the npm registry. So we tag this first version (new releases should be done with npm version which automatically tags them), push to GitHub, push tags and finally publish to npm:
. Publishing our module

That’s it! Our module lives in the npm registry.

5. Completing our README

Our module can be used by anyone, but sadly, the page for it looks like this:
Completing our README

It’s empty and sad, no explanation on how to use it, nothing. We should definitely add a few things: basic badges, how to install, how to use, related packages and a footer stating our copyright and the license. For our module it looks like this:

# express-debug-async-wrap [![npm](https://img.shields.io/npm/v/express-debug-async-wrap.svg?style=flat-square)]() [![npm](https://img.shields.io/npm/dm/express-debug-async-wrap.svg?style=flat-square)]() [![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg?style=flat-square)](https://standardjs.com) [![npm](https://img.shields.io/npm/l/express-route-autoloader.svg?style=flat-square)](LICENSE)
express async wrapper that passes custom debug instance and returns 400 as default error code
## Install
```
npm i -S express-debug-async-wrap
or
npm install --save express-debug-async-wrap
```
## Use
Require and initialize with `debug` instance:
```js
const debug = require('debug')('backend:routes:doc')
const wrapper = require(`express-debug-async-wrap`)(debug)
const express = require('express')
const router = express.Router()
router.get('/', wrapper(async (req, res) => {
  await ...
  await ...
  res.send('OK')
}))
module.exports = router
```
## Related
- [express-route-autoloader](https://github.com/DiegoRBaquero/express-route-autoloader)
- [sequelize-express-findbyid](https://github.com/DiegoRBaquero/sequelize-express-findbyid)
## License
MIT Copyright © [Diego Rodríguez Baquero](https://diegorbaquero.com)

Once it’s done, we must create a patch version, push to GitHub and publish to npm. After committing our changes:

That’s it!

6. Final touches and homework

  • Important: Add tests and setup CI! (Travis recommended)

  • Add more badges: travis build, security related, etc. Here’s an example:
    Final touches and homework

  • Share your module in social media, forums, IRC/Gitter channels

  • Tell me how you did and share me your module.

  • Learn more about npm

Diego

Diego RBaquero

Blog Author
Senior Backend Developer at Inalambria. FOSS Advocate. WebTorrent Core Member

Leave a Reply

Your email address will not be published. Required fields are marked *

SUBSCRIBE OUR BLOG

Follow Us On

Share on

other Blogs

20% Discount