How To Use npm to Build and Publish Node.js Packages on a Linux Server

First, let’s see what our current settings are. We can do this by typing:

npm config ls

; cli configs
registry = "https://registry.npmjs.org/"
user-agent = "npm/1.4.9 node/v0.11.13 linux x64"

; node bin location = /home/demouser/.nvm/v0.11.13/bin/node
; cwd = /home/demouser/projects/test_package
; HOME = /home/demouser
; 'npm config ls -l' to show all defaults.

This list of settings is pulled from a variety of different places, including the current operating environment. It is built when the command is run. You can test this by passing the -g flag. It will suddenly show that the “global” option is set:

<pre> npm config ls -g </pre> <pre> ; cli configs <span class=“highlight”>global = true</span> registry = “https://registry.npmjs.org/” user-agent = “npm/1.4.9 node/v0.11.13 linux x64” . . . </pre>

Right now, npm is not pulling any information from its configuration files because there are no configuration files that have been created yet. It is simply gathering information from its environment (current directory, etc.) and using the application defaults.

We aren’t shown most of the defaults with this command though. To get more extensive information, we’ll have to pass the -l flag:

npm config ls -l

; cli configs
long = true
registry = "https://registry.npmjs.org/"
user-agent = "npm/1.4.9 node/v0.11.13 linux x64"

; default values
always-auth = false
bin-links = true
browser = null
ca = null
. . .

As you can see, there are many key-value pairs of information. This is how we work with configuration values within npm. For instance, if we want to see the current value of the “editor” key, we can type:

npm config get editor

vi

If we want to change this value, we can easily do that by typing something like this:

<pre> npm config set editor <span class=“highlight”>vim</span> </pre>

This will do two things. It will override the default value (vi) with our new value (vim), and it will also create our configuration file, since it is our first custom value.

Where is our configuration file written? Why don’t we ask npm:

npm config get userconfig

/home/demouser/.npmrc

If we set values using the config set -g syntax, they will be written to our globalconfig file. We can find out where this is stored by typing:

npm config get globalconfig

/home/demouser/.nvm/v0.11.13/etc/npmrc

Your file location will differ depending on the method you used to install Node.js. Again, this file won’t exist until you stray from the default values on the global level.

For the file that does exist, if you want to edit it with your editor, you can do that by typing:

npm config edit

This will not work if the file hasn’t already been created yet (manually or by setting a non-default value within npm).

You can also set different configuration options for a specific command as you are calling it by using this syntax:

<pre> npm <span class=“highlight”>subcommand</span> --<span class=“highlight”>key</span> <span class=“highlight”>value</span> </pre>

Other areas where values are pulled from are the package.json file for the project itself and environmental variables.

When you have created a package that you wish to share with the greater Node.js community, the npm site is a great place to start.

Fortunately, npm comes with some helper functions that will get you started.

If you are in your package’s directory, you can simply type:

npm publish

This will push your package onto the npm website. The success of this operation is dependent on your package having a unique name and version number. If you go there and search for your package, it should be listed just like any other Node.js package.

You can tag specific releases of your packages by using the tag subcommand. These can be used in place of version numbers during installation and dependency specifications.

By default, npm will include a tag labeled “latest” to any package you publish. This just marks the most recent push. You can see this by typing:

npm config get tag

latest

This means that you can specifically request the latest version by typing things like:

npm install package@latest

If you want to add an additional tag to one of your package/version combinations, you can type something like:

<pre> npm tag <span class=“highlight”>package</span>@<span class=“highlight”>version</span> <span class=“highlight”>tag_name</span> </pre>

This will let you now reference the version you tagged by the “tag_name” instead of the version number.

By default, when you publish a package, you will be given ownership of the package.

You can verify this by typing:

<pre> npm owner ls <span class=“highlight”>package_name</span> </pre> <pre> demouser <demouser@domain.com> </pre>

If you want to add additional people to the project, which will allow them to make modifications, you can issue a command like this:

<pre> npm owner add <span class=“highlight”>username</span> </pre>

You can also do the reverse of this and remove rights from users like this:

<pre> npm owner rm <span class=“highlight”>username</span> </pre>

At the time of this writing, all owners for a package have the same rights, so it is not possible to assign more fine-grained access control.

Sometimes, there is an important change in your package that make it necessary to deprecate older versions. For example, maybe there was a security problem.

With npm, you can easily deprecate a version or a version range of your package by typing something like this:

<pre> npm deprecate <span class=“highlight”>package_name</span>@“<span class=“highlight”>version_or_range</span” “<span class=“highlight”>deprecation_message_to_users</span>” </pre>

The message that you choose to include will be shown as a warning to any user installing the package versions you’ve marked.

If you want to take your package down entirely, you can do that by unpublishing it. You should probably not do this if your package has been used by other people and npm encourages you to deprecate the package instead. You can also unpublish a specific version, but the same suggestion holds.

An important thing to note is that even if you unpublish a package and it is removed from the site, the name/version combinations it held cannot be reused ever. This is to ensure that people are not accidentally pulling the wrong packages.

The syntax for unpublishing your work is:

<pre> npm unpublish <span class=“highlight”>package_name</span>@<span class=“highlight”>version</span> </pre>

You can leave off the @version if you want to remove the entire package. In this case, you’ll have to add the --force flag so avoid accidental deletion of your entire project:

<pre> npm unpublish --force <span class=“highlight”>package_name</span> </pre>