Notesheet: Node Package Manager (npm)

Posted on | by Jason Snelders

Updated: 31 January 2020

 

The npm website is: https://www.npmjs.com/.

Note: As npm evolves some commands may change or become deprecated. We’ve already seen this with v5 (–save is now added by default during npm install) and v5 (npm audit seems to have replaced nsp check). Such is the ways of software development.

This chaetsheet was created with front-end web development in mind.

 

Initialising

  • npm init: Asks questions to create a package.json file.
  • npm init -y: Create package.json with all default answers accepted.
  • npm set: Set defaults for when you run npm init.
  • npm get: Check a default setting used when running npm init.
  • npm config delete: Remove a default setting used when running npm init.
  • Settings are stored in the ~/.npmrc file in the root of the user directory.

 

Installing packages

  • npm install {package_name}: Install a package in your projects. Installs to the “node_modules” sub-directory of your current directory. Installs the latest version.
  • npm install {package_name} –save: Save it to the dependencies section of package.json file.
  • npm install {package_name} –save-dev: Save it to the ‘dev’ dependencies list of package.json file.
  • Install packages globally so they can be used across projects.
  • npm install {package_name} -g: Install a package globally to a special folder on your computer.
  • npm install {package_name}@{version_number}: Install a specific version of a package locally.
  • In package.json: 
    {
  "dependencies": { "underscore": "^1.8.3" }
}

    The “^” means if a new version of the package is published, the newest version will be installed (auto upgraded).
    It also means we only want the latest version of the major release (the first digit, in this example the minor version is 1).

  • In package.json: 
    {
  "dependencies": { "underscore": "~1.8.3" }
}

    The “~” means we only want the latest version of the minor release (the second digit, in this example the minor version is 1.8).

  • In package.json: 
    {
  "dependencies": { "underscore": "*" }
}

    The “*” means just wan the latest version of the library (regardless of major or minor release).

  • In package.json: 
    {
  "dependencies": { "underscore": "1.8.3" }
}

    Just the number means we even install that exact version of the library (in this example, 1.8.3).

  • npm install {package_name}@{version_number} –save –save-exact: Install a version of a package, and tell package.json to use the exact version (don’t auto upgrade) via the –save-exact flag.
  • After package.json is setup, a new use just needs to use npm install to install all package dependencies.
  • npm install {url}: Install a package from a specified URL (e.g. GitHub or hosted server).
  • npm install gist:{github_gist_hash}: Install a package from a GitHub gist. You can use –save with it.
    • After, if you use npm list you may see it marked with “npm ERR!  extraneous: ….”. That means “the package is installed but is not listed in your project’s package.json”.
    • If you save it to packages.json then list it out you may see it as “invalid”. You can ignore that. It has to do with not being in the npm registry.
  • To install a private/closed source package from a folder: npm install {path_to_package_folder}. (e.g. “npm install ../my-package”).
  • npm list: List of packages you’ve installed locally, with their dependent packages.
    • list will return a complete dependency tree, with all sub-sub-sub-etc dependencies.
    • You can return just the first level of packages by using npm list –depth=0. To include the first sub-level of package dependencies,
    • npm list –depth=1.
  • npm list –global or npm list -g: List of packages you’ve installed globally, with their dependent packages.
    • You can use –depth=x after -g same as with local packages.

 

Updating Packages

  • npm outdated: Checks the npm registry to see if any of the installed packages are outdated (i.e. newer versions are available).
  • npm update: npm will get the latest compatible version of your dependencies and updates them
    (Question: is this only looking at package.json? What if there is no package.json – does it just look at the installed modules? According to https://www.hostingadvice.com/how-to/update-npm-packages/: “The npm update command allows you to update any out-of-date packages, according to your package.json versions”. So my takeaway is that npm update requires package.json).
  • npm update –dev and npm update –prod: Update just development dependencies or production dependencies, respectively.
  • npm update {package_name}: Update a single dependency/package.
  • npm update -g: Update all global dependencies.
  • npm update -g {package_name}: Update a single package in global dependencies.

 

Removing Packages

  • npm uninstall {package_name}: Uninstall a package locally. Does not remove from the “dependencies in your package.json file.
  • npm uninstall {package_name} –save: Uninstall a package locally and remove from the “dependencies in your package.json file.
  • npm uninstall {package_name} -g: Uninstall a package from the global repository.
  • Pruning: Removing packages that are not listed in your package.json file (e.g. if you run npm list and notice an “extraneous” error in the results).
  • npm prune: Goes through and compares installed local packages to the package.json file and removes anything that should not be there.
  • npm prune {package_name}: Prune a single package. Essentially the same as npm remove.
  • npm prune –production: Removes all dev dependencies, which will leave your package (?? no, project) ready to go to production.

 

Running Scripts

  • Scripts: Create scripts that can be run in the “scripts” section of package.json
    • 2 default scripts: “test” and “start”.
    • npm test: Run the “test” script.
    • npm start: By convention, the script you will run to launch the project.
    • Example section in package.json: 
      {
  "scripts": {
    "test": "node test.js",
    "start": "node index.js",
  }
}
    • For other supported script names see https://docs.npmjs.com/misc/scripts.
    • You can also use your own custom script names (e.g. “uglify”: “gulp compress” to use gulp to compress and uglify the code. So you would run “npm run uglify”).
    • npm run {script}: Run a custom script.
    • The scripts section is good guidance for other developers on tasks to run in the project.

 

Other Actions

  • npm repo {package_name}: Take you to the official source repository for the package.
  • To upgrade NPM itself: npm install@latest -g. Note: must be run on a command-prompt with administrator privileges.
  • npm audit: (since npm v6) Run a security check on your dependencies (packages) for security issues.

 

Resources/tutorials