How To: Publishing Your First Package to npm

Let’s create a folder that’s going to hold our package’s source code. In your terminal:

# This will create, and navigate
# into the `wonderful-bundle` directory
$ mkdir wonderful-bundle
$ cd wonderful-bundle

Now that you’re in the folder, here’s where we start using npm commands!

$ npm init

Running npm init will ask you a few setup questions (for example, the name of your package, your package’s description, etc).

You can simply hit “Enter” for each question and this default boilerplate for package.json file will be created in your directory:

{
  "name": "wonderful-bundle",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
      "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

You can compare the package.json file to a recipe card for your favorite meal.

The package.json file contains all of the descriptive metadata about the project (like the name “Apple Crumb Pie”), and all of the dependencies needed to properly run it (the ingredients: “apples”, “pie crust”, “sugar”, etc).

Using all of this info, npm brings everything together so that your package can be effortlessly downloaded & run by other people.

Let’s edit package.json to include a description, and author information.

{
  "name": "wonderful-bundle",
  "version": "1.0.0",
  "description": "outputs an uplifting message",
  "main": "index.js",
  "author": "Chompy MacPherson <chompymac@alligator.io>",
  "license": "ISC"
}

The only fields that are required in package.json are “name”, “version”, and “main”. The “scripts” field was removed since we don’t have any tests written yet.

The “main” field is the file path to the JavaScript code. When someone uses your package this JavaScript file will be used. Let’s create the index.js file in our terminal:

$ touch index.js

In a text editor of your choice…

module.exports = function() {
  console.log("you're wonderful!");
  return;
};

Remember to export your code in the same way you would for files that are local to your software project.

Generally it’s a good idea to include documentation for your package so others know how to use it. The README file is typically used for this purpose.

Let’s create the README file in the root of your package’s directory:

# create the README file
$ touch README

# put some text into README
$ echo "## Wonderful Bundle \n\n Get an uplifting message!" > README

Currently, this is what the file directory for wonderful-bundle looks like:

wonderful-bundle
 |_ index.js
 |_ README
 |_ package.json

Essentially, this is the basic structure of a npm package. Not much is needed to publish your software to npm!

Now that we feel pretty good about our package, let’s publish it!

$ npm publish