Examples

• 83

  Installing packages

  edit move example delete share

  83

  Introduction

  Packages are a term used by npm to denote tools that developers can use for their projects. These include everything from libraries and frameworks such as jQuery and AngularJS to task runners such as Gulp.js. The packages will come in a folder typically called node_modules, which will also contain a package.json file. This file will give information regarding the package including any dependencies, which are additional modules needed to use the package.

  Npm uses the command line to both install and manage packages, so users attempting to use npm should be familiar with basic commands on their operating system i.e.: traversing directories as well as being able to see the contents of directories.

  ---

  How to install packages

  To install one or more packages use the following. Note that this will install the package in the directory that the command line is currently in, thus it is important to check whether the appropriate directory has been chosen:

  npm install <package-name>
  # or
  npm i <package-name>...
  
  # e.g. to install lodash and express
  npm install lodash express
  

  If you already have a package.json file in your current working directory and dependencies are defined in it, then npm install will automatically resolve and install all dependencies listed in the file. You can also use the shorthand version of the npm install command which is: npm i

  If you want to install a specific version of a package use:

  npm install <name>@<version>
  
  # e.g. to install version 4.11.1 of the package lodash
  npm install [email protected]
  

  If you want to install a version which matches a specific version range use:

  npm install <name>@<version range>
  
  # e.g. to install a version which matches "version >= 4.10.1" and "version < 4.11.1"
  # of the package lodash
  npm install lodash@">=4.10.1 <4.11.1"
  

  If you want to install the latest version use:

  npm install <name>@latest
  

  The above commands will search for packages in the central npm repository at npmjs.com. If you are not looking to install from the npm registry, other options are supported, such as:

  # packages distributed as a tarball
  npm install <tarball file>
  npm install <tarball url>
  
  # packages available locally
  npm install <local path>
  
  # packages available as a git repository
  npm install <git remote url>
  
  # packages available on GitHub
  npm install <username>/<repository>
  
  # packages from a specific repository
  npm install --registry=http://myreg.mycompany.com <package name>
  
  # packages from a related group of packages 
  # See npm scope
  npm install @<scope>/<name>(@<version>)
  
  # Scoping is useful for separating private packages hosted on private registry from
  # public ones by setting registry for specific scope
  npm config set @mycompany:registry http://myreg.mycompany.com
  npm install @mycompany/<package name>
  

  Usually, modules will be installed locally in a folder named node_modules, which can be found in your current working directory. This is the directory require() will use to load modules in order to make them available to you.

  If you already created a package.json file, you can use the --save (shorthand -S) option or one of its variants to automatically add the installed package to your package.json as a dependency. If someone else installs your package, npm will automatically read dependencies from the package.json file and install the listed versions. Note that you can still add and manage your dependencies by editing the file later, so it's usually a good idea to keep track of dependencies, for example using:

  npm install --save <name> # Install dependencies 
  # or
  npm install -S <name> # shortcut version --save 
  # or
  npm i -S <name>
  

  ---

  Installing dependencies

  Some modules do not only provide a library for you to use, but they also provide one or more binaries which are intended to be used via the command line. Although you can still install those packages locally, it is often preferred to install them globally so the command-line tools can be enabled. In that case, npm will automatically link the binaries to appropriate paths (e.g. /usr/local/bin/<name>) so they can be used from the command line. To install a package globally, use:

  npm install --global <name>
  # or
  npm install -g <name>
  # or
  npm i -g <name>
  
  # e.g. to install the grunt command line tool
  npm install -g grunt-cli
  

  If you want to see a list of all the installed packages and their associated versions in the current workspace, use:

  npm list
  npm list <name>
  

  Adding an optional name argument can check the version of a specific package.

  ---

  Note: If you run into permission issues while trying to install an npm module globally, resist the temptation to issue a sudo npm install -g ... to overcome the issue. Granting third-party scripts to run on your system with elevated privileges is dangerous. The permission issue might mean that you have an issue with the way npm itself was installed. If you're interested in installing Node in sandboxed user environments, you might want to try using nvm.

  If you have build tools, or other development-only dependencies (e.g. Grunt), you might not want to have them bundled with the application you deploy. If that's the case, you'll want to have it as a development dependency, which is listed in the package.json under devDependencies. To install a package as a development-only dependency, use --save-dev (or -D).

  npm install --save-dev <name> // Install development dependencies which is not                      include in producation 
  # or
  npm install -D <name>
  

  You will see that the package is then added to the devDependencies of your package.json.

  To install dependencies of a downloaded/cloned node.js project, you can simply use

  npm install
  # or
  npm i
  

  npm will automatically read the dependencies from package.json and install them.

  edited Sep 19 at 8:44

  

  

  

  

  

  +23
• 27

  Uninstalling packages

  edit move example delete share

  27

  To uninstall one or more locally installed packages, use:

  npm uninstall <package name>
  

  The uninstall command for npm has five aliases that can also be used:

  npm remove <package name>
  npm rm <package name>
  npm r <package name>
  
  npm unlink <package name>
  npm un <package name>
  

  If you would like to remove the package from the package.json file as part of the uninstallation, use the --save flag (shorthand: -S):

  npm uninstall --save <package name>
  npm uninstall -S <package name>
  

  For a development dependency, use the --save-dev flag (shorthand: -D):

  npm uninstall --save-dev <package name>
  npm uninstall -D <package name>
  

  For an optional dependency, use the --save-optional flag (shorthand: -O):

  npm uninstall --save-optional <package name>
  npm uninstall -O <package name>
  

  For packages that are installed globally use the --global flag (shorthand: -g):

  npm uninstall -g <package name>
  

  edited Jul 30 at 0:29

  

  

  

  

  

  +1
• 21

  Setting up a package configuration

  edit move example delete share

  21

  Node.js package configurations are contained in a file called package.json that you can find at the root of each project. You can setup a brand new configuration file by calling:

  npm init
  

  That will try to read the current working directory for Git repository information (if it exists) and environment variables to try and autocomplete some of the placeholder values for you. Otherwise, it will provide an input dialog for the basic options.

  If you'd like to create a package.json with default values use:

  npm init --yes
  # or
  npm init -y 
  

  If you're creating a package.json for a project that you are not going to be publishing as an npm package (i.e. solely for the purpose of rounding up your dependencies), you can convey this intent in your package.json file:

  1. Optionally set the private property to true to prevent accidental publishing.
  2. Optionally set the license property to "UNLICENSED" to deny others the right to use your package.

  To install a package and automatically save it to your package.json, use:

  npm install --save <package>
  

  The package and associated metadata (such as the package version) will appear in your dependencies. If you save if as a development dependency (using --save-dev), the package will instead appear in your devDependencies.

  With this bare-bones package.json, you will encounter warning messages when installing or upgrading packages, telling you that you are missing a description and the repository field. While it is safe to ignore these messages, you can get rid of them by opening the package.json in any text editor and adding the following lines to the JSON object:

  [...]
  "description": "No description",
  "repository": {
    "private": true
  },
  [...]
  

  edited Jul 26 at 7:09

  

  

  

  

  

  +1
• 9

  Running scripts

  edit move example delete share

  9

  You may define scripts in your package.json, for example:

  {
    "name": "your-package",
    "version": "1.0.0",
    "description": "",
    "main": "index.js",
    "author": "",
    "license": "ISC",
    "dependencies": {},
    "devDependencies": {},
    "scripts": {
      "echo": "echo hello!"
    }
  }
  
  

  To run the echo script, run npm run echo from the command line. Arbitrary scripts, such as echo above, have to be be run with npm run <script name>. npm also has a number of official scripts that it runs at certain stages of the package's life (like preinstall). See here for the entire overview of how npm handles script fields.

  npm scripts are used most often for things like starting a server, building the project, and running tests. Here's a more realistic example:

    "scripts": {
      "test": "mocha tests",
      "start": "pm2 start index.js"
    }
  

  In the scripts entries, command-line programs like mocha will work when installed either globally or locally. If the command-line entry does not exist in the system PATH, npm will also check your locally installed packages.

  If your scripts become very long, they can be split into parts, like this:

    "scripts": {
      "very-complex-command": "npm run chain-1 && npm run chain-2",
      "chain-1": "webpack",
      "chain-2": "node app.js"
    }
  

  edited Aug 6 at 21:42

  

  

  

  

  
• 7

  Basic semantic versioning

  edit move example delete share

  7

  Before publishing a package you have to version it. npm supports semantic versioning, this means there are patch, minor and major releases.

  For example, if your package starts at version 1.0.0 to change version you have to:

  1. patch release: npm version patch => 1.0.1
  2. minor release: npm version minor => 1.1.0
  3. major release: npm version major => 2.0.0

  You can also specify a version directly with:

  npm version 3.1.4 => 3.1.4

  When you set a package version using one of the npm commands above, npm will modify the version field of the package.json file, commit it, and also create a new Git tag with the version prefixed with a "v", as if you've issued the command:

  git tag v3.1.4

  Unlike other package managers like Bower, the npm registry doesn't rely on Git tags being created for every version. But, if you like using tags, you should remember to push the newly created tag after bumping the package version:

  git push origin master (to push the change to package.json)

  git push origin v3.1.4 (to push the new tag)

  Or you can do this in one swoop with:

  git push origin master --tags

  edited Aug 6 at 21:26

  

  

  

  
• 5

  Publishing a package

  edit move example delete share

  5

  First, make sure that you have configured your package (as said in Setting up a package configuration​). Then, you have to be logged in to npmjs.

  If you already have a npm user

  npm login
  

  If you don't have a user

  npm adduser
  

  To check that your user is registered in the current client

  npm config ls
  

  After that, when your package is ready to be published use

  npm publish
  

  And you are done.

  If you need to publish a new version, ensure that you update your package version, as stated in Basic semantic versioning. Otherwise, npm will not let you publish the package.

  {
      name: "package-name",
      version: "1.0.4"
  }
  

  edited Aug 1 at 18:01

  

  

  
• 4

  Listing currently installed packages

  edit move example delete share

  4

  To generate a list (tree view) of currently installed packages, use

  npm list
  

  ls, la and ll are aliases of list command. la and ll commands shows extended information like description and repository.

  Options

  The response format can be changed by passing options.

  npm list --json
  

  • json - Shows information in json format
  • long - Shows extended information
  • parseable - Shows parseable list instead of tree
  • global - Shows globally installed packages
  • depth - Maximum display depth of dependency tree
  • dev/development - Shows devDependencies
  • prod/production - Shows dependencies

  If you want, you can also go to the package's home page.

  npm home <package name>
  

  edited Sep 11 at 17:33

  

  

  

  
• 4

  Removing extraneous packages

  edit move example delete share

  4

  To remove extraneous packages (packages that are installed but not in dependency list) run the following command:

  npm prune
  

  To remove all dev packages add --production flag:

  npm prune --production
  

  More on it

  edited Jul 27 at 9:06

  

  

  
• 4

  Scopes and repositories

  edit move example delete share

  4

  # Set the repository for the scope "myscope"
  npm config set @myscope:registry http://registry.corporation.com
  
  # Login at a repository and associate it with the scope "myscope"
  npm adduser --registry=http://registry.corporation.com --scope=@myscope
  
  # Install a package "mylib" from the scope "myscope"
  npm install @myscope/mylib
  

  If the name of your own package starts with @myscope and the scope "myscope" is associated with a different repository, npm publish will upload your package to that repository instead.

  You can also persist these settings in a .npmrc file:

  @myscope:registry=http://registry.corporation.com
  //registry.corporation.com/:_authToken=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxx
  

  This is useful when automating the build on a CI server f.e.

  edited Sep 21 at 16:18

  

  
• 3

  Linking projects for faster debugging and development

  edit move example delete share

  3

  Building project dependencies can sometimes be a tedious task. Instead of publishing a package version to NPM and installing the dependency to test the changes, use npm link. npm link creates a symlink so the latest code can be tested in a local environment. This makes testing global tools and project dependencies easier by allowing the latest code run before making a published version.

  Help text

  NAME
         npm-link - Symlink a package folder
  
  SYNOPSIS
           npm link (in package dir)
           npm link [<@scope>/]<pkg>[@<version>]
  
           alias: npm ln
  

  Steps for linking project dependencies

  When creating the dependency link, note that the package name is what is going to be referenced in the parent project.

  1. CD into a dependency directory (ex: cd ../my-dep)
  2. npm link
  3. CD into the project that is going to use the dependency
  4. npm link my-dep or if namespaced npm link @namespace/my-dep

  Steps for linking a global tool

  1. CD into the project directory (ex: cd eslint-watch)
  2. npm link
  3. Use the tool
  4. esw --quiet

  Problems that may arise

  Linking projects can sometimes cause issues if the dependency or global tool is already installed. npm uninstall (-g) <pkg> and then running npm link normally resolves any issues that may arise.

  created Aug 6 at 21:29

  
• 2

  Locking modules to specific versions

  edit move example delete share

  2

  By default, npm installs the latest available version of modules according to each dependencies' semantic version. This can be problematic if a module author doesn't adhere to semver and introduces breaking changes in a module update, for example.

  To lock down each dependencies' version (and the versions of their dependencies, etc) to the specific version installed locally in the node_modules folder, use

  npm shrinkwrap
  

  This will then create a npm-shrinkwrap.json alongside your package.json which lists the specific versions of dependancies.

  created Jul 31 at 1:59

  
• 2

  Setting up for globally installed packages

  edit move example delete share

  2

  You can use npm install -g to install a package "globally." This is typically done to install an executable that you can add to your path to run. For example:

  npm install -g gulp-cli
  

  If you update your path, you can call gulp directly.

  On many OSes, npm install -g will attempt to write to a directory that your user may not be able to write to such as /usr/bin. You should not use sudo npm install in this case since there is a possible security risk of running arbitrary scripts with sudo and the root user may create directories in your home that you cannot write to which makes future installations more difficult.

  You can tell npm where to install global modules to via your configuration file, ~/.npmrc. This is called the prefix which you can view with npm prefix.

  prefix=~/.npm-global-modules
  

  This will use the prefix whenever you run npm install -g. You can also use npm install --prefix ~/.npm-global-modules to set the prefix when you install. If the prefix is the same as your configuration, you don't need to use -g.

  In order to use the globally installed module, it needs to be on your path:

  export PATH=$PATH:~/.npm-global-modules/bin
  

  Now when you run npm install -g gulp-cli you will be able to use gulp.

  Note: When you npm install (without -g) the prefix will be the directory with package.json or the current directory if none is found in the hierarchy. This also creates a directory node_modules/.bin that has the executables. If you want to use an executable that is specific to a project, it's not necessary to use npm install -g. You can use the one in node_modules/.bin.

  edited Sep 19 at 8:54

  

  
• 2

  Updating npm and packages

  edit move example delete share

  2

  Since npm itself is a Node.js module, it can be updated using itself.

  npm install -g npm@latest
  

  If you want to check for updated versions you can do:

  npm outdated
  

  In order to update a specific package:

  npm update <package name>
  

  This will update the package to the latest version according to the restrictions in package.json

  In case you also want to lock the updated version in package.json:

  npm update <package name> --save
  

  edited Sep 11 at 17:33