1.6. Working with npm packages

There are two ways to install npm packages:

  • Locally
  • Globally

You should choose one way or another depending on the way that you want to use the package from your own modules you should use a local installation. On the other hand, if you are planning to use the package from the command line interface you use a global installation.

How to do it…

In this section, we are going to learn how to install, update and uninstall npm packages.

  1. A package can be locally installed using the npm install command:
    $ npm install typescript
    

    The preceding command will create a folder named node_modules in the current directory, download the typescript module and save it inside the node_modules folder.

  2. Installing global packages is really straightforward, all you need to do is to use the –g option together with the npm install command:
    $ npm install –g typescript
    

    If you get an EACCES error, you will need to fix your npm permissions or try again with the sudo command:

    $ sudo npm install –g typescript
    
  3. You can check if your local packages are up to date by executing the following command:
    $ npm outdated
    
  4. You can also find out which global packages need to be updated using the following command:
    $ npm outdated -g --depth=0
    
  5. If there are some outdated local packages, you can use the following command in the same directory as your package.json file to update the outdated packages:
    $ npm update
    

    Just like in the case of local packages, you can update global packages using the npm install command. The only difference is that you must use the –g flag.

    $ npm update -g jshint
    
  6. You can delete a local package from the node_modules folder using the following command:
    $ npm uninstall jquery
    

    It is important to know that the command above will not remove the reference to that package in the package.json file.

  7. Just like in the case of local packages, you can uninstall global packages using the npm uninstall command. The only difference is that you must use the –g flag.
    $ npm uninstall -g jshint
    

How it works…

Now it’s important to understand how npm install/update/uninstall works internally:

  • The npm package uses a special file named package.json to store reference to the installed packages and their versions.
  • When you install a new package, npm will look for the package.json file to determine which version should be installed.
  • If the package.json file is not available, the latest version of the package will be installed. If the package.json file is available, the latest version satisfying the version specified in package.json for that package is installed.
  • Similarly, if you update an existing npm package, npm checks if next version of package is available, if it is, npm updates the same in node_modules and if you try to uninstall a npm package from local/global node_modules it looks into node_modules folder and if founds it, npm removes that from the folder as well from the package.json.

There’s more…

  • You can also install a specific version of a package using a special naming convection known as semantic versioning or semver. For example, if you want to install the version 3.2.1 of the JQuery package you must use the following command:
    $ npm install jquery@3.2.1
    
  • You can also install the latest version using the following command:
    $ npm install jquery@latest
    
  • You can generate a package.json file by using the following command:
    $ npm init
    
  • The preceding command will request you to answer a few questions and will generate a package.json file on the current directory at the end of the process.
  • You can use the --save and --save-dev options to add reference the installed packages in your package.json file. The --save option is used to reference run time dependencies, while the --save-dev options is used to reference development dependencies:
    $ npm install jquery --save
    $ npm install karma --save-dev
    
  • It is easy to forget to remove the package from both the node_modules and package.json file. For that reason, it is recommended to use the following command to list all the installed packages and their status:
    $ npm ls
    
  • If the dependency has not been fully removed or fully installed it will be listed as:
    • Unmet dependency: A dependency that has been declared in the package.json but has not been downloaded and saved into the node_modules folder. Or a dependency that has been removed from the node_modules folder but we forgot to remove from the package.json file.
    • Extraneous dependency: A dependency that has been downloaded and saved into the node_modules directory but is not referenced in the package.json file.
  • If you are removing a dependency, you should remove it from both the node_modules and the package.json to avoid unmet dependencies. We can achieve this using the --save option together with the uninstall command.
    $ npm uninstall jquery --save
    
  • In the case of extraneous dependencies, we can remove the packages from the node_modules folder by using the following command:
    $ npm prune
    

See also

Please refer to the section Fixing npm permissions in this chapter to learn more about npm permissions issues.
Please refer to the section about semantic versioning, which can be found later in this chapter to learn more about it.
You can learn more about the package.json file at https://docs.npmjs.com/files/package.json.


Shiv Kushwaha

Author/Programmer