1.9. Creating and publishing npm packages

The node package manager allows us to publish Node.js modules but it can also be used to publish other kind of packages like, for example, style sheet libraries. We will void into details about how to implement Node.js packages in this chapter because we will focus on Node.js development in Chapter 8, Creating server applications with Node.js.

How to do it…

We are going to publish a npm package:

  1. To publish a package, you must first create a package.json file:
    $ npm init
  2. The preceding command will launch a command line wizard, which will generate a package.json file for us. The wizard will ask for the following fields:

    Field Description
    Name The name of your package
    Version The version of your package. It must start with the version 1.0.0 and follow the semantic versioning convection.
    Entry point The file that will be loaded when someone loads your package.
    Test command The command that must be executed to execute the automated tests of your package.
    Git repository The URL of the Git repository
    Keywords Keywords used to help other developers to find your package in the npm website.
    Author The author field follows the following format: name (website)
    License The software license of your module
  3. After creating the package.json file, you need to create a npm account. You can do it using the command line:
    $ npm adduser
  4. The command will ask for a user name and password. You can test that everything worked as expected by visiting the following URL: https://www.npmjs.com/~kushwahashiv

    Note that the preceding URL is using my user name: kushwahashiv. You must replace it with your user name.

  5. Once you have an npm user account and a package.json file, you will be able to use the following command to publish the package:
    $ npm publish
  6. You package will then become public and anyone in the internet will be able to install it using npm install:
    $ npm install your_package_name

    We are now going to create and publish a scoped npm package. If the name of a package starts with @, then it is a scoped package:


    Your npm user can be used as the scope of your packages: @organization-name/package-name

  7. To create a scoped package, you just need to use a package name that starts with your scope in package.json:
      "name": "@scope/name"
  8. You can also auto-generate a package.json file for a scoped package using the npm init command as follows:
    $ npm init --scope=scope

    In some scenarios, it may be common to use scope for all your packages. For example, if you are working for a company, all the Node.js modules could use the name of the company as their scope. In that case it would be recommended to add the scope to the ~/.npmrc file.

    $ npm config set scope username

    Please refer to the section Editing the npm configuration files, which can be found in this chapter to learn more about the .npmrc file.

How it works…

Semantic versioning helps developers to communicate what kind of changes are included on a new release. Communicating what kind of changes are released is important because sometimes a new version can break the applications that consume the package. Semantic versioning resolves this issue by using the following version numbering convection:

  • Increasing the first number: Indicates that the release is not blackguards compatible with the previous version. This kind of release is known as major release.
  • Increasing the second number: Indicates that the release won’t break existing features. This kind of release is known as minor release.
  • Increasing the third number: Indicates that the release includes some bug fixes. This kind of release is known as patch release. Now you should have a have a better understanding of the npm version command:
    $ npm version major | minor | patch

There’s more…

  • If you do some changes to your package and try to publish it again you will get the following error:
    ERR! "You cannot publish over the previously published version 1.0.0."

    This error is used to avoid the overriding of an existing version of an npm package. You can use the npm version command to increment the version number of your package. This time we will pass patch to the npm version command to update the last number in the semantic version number:

    $ npm version patch

    After running the command, the version of your package should be 1.0.1. You might be wondering why patch only updated the last number in the version. It is that way because npm follows a standard naming convection for software releases known as semantic versioning.

  • Scoped packages are private by default and a subscription as private modules user is required to publish private modules. However, public scoped modules can be published for free by setting the access option when publishing. This option will remain set for all subsequent publishes.
    $ npm publish --access=public
  • After publishing the public scoped module, you can install it using the npm install command:
    $ npm install @organization-name/package-name –-save

See also

If you run the npm version command in a git repository it will also add git tags. You can learn more about git tags at https://git-scm.com/book/en/v2/Git-Basics-Tagging. Also, refer to the following link if you wish to learn more about semantic versioning: https://docs.npmjs.com/misc/semver.

Shiv Kushwaha