A list of terminal commands and flags to help use npm.
- Basic npm commands
- Package creation
- Package management
- List packages
- npm versioning
- Updating Packages
- NPM Prune
- Dependencies and Development Dependencies
- Exploring package information and versions
- Configure NPM
- NPM Script
- Custom NPM scripts
- Resources
Check version number of npm:
npm -version
Or use shorthand:
npm -v
Get help on npm:
npm help
Quick help for specific command:
npm <command> -h
Example:
npm install -h
Search npm documentation and return the result:
npm help -search <command>
Example:
npm help -search install
Read documentation of any specific package online (official):
npm docs <package>
Example:
npm docs lodash
Update npm to latest version:
npm install npm@latest -g
Initialize project and create package.json file:
npm init
💡 Note: Follow the wizard dilligently.
Initialize project and create package.json file with default values:
npm init --yes
Or use shorthand:
npm init --y
Set default author name for package.json:
npm config set init -author-name ‘your-name’
Set default license for package.json:
npm set init -license ‘MIT’
Show default author name:
npm config get init -author-name
Show default license:
npm get init -license
Delete default author name:
npm config delete init -author-name
Delete default license:
npm config delete init -license
package.json file:
Package name - If you plan to publish your package, the most important things in your package.json are the name and version fields as they will be required. The name and version together form an identifier that is assumed to be completely unique.
Changes to the package should come along with changes to the version. If you do not plan to publish your package, the name and version fields are optional.
Rules:
- The name must be less than or equal to 214 characters. This includes the scope for scoped packages.
- The name can not start with a dot or an underscore.
- New packages must not have uppercase letters in the name
- The name ends up being part of a URL, an argument on the command line, and a folder name. Therefore, the name can’t contain any non-URL-safe characters.
Version - Version number of your package.
Description - It’s a string. This helps people discover your package, as it’s listed in npm search.
Entry point - We write a file which includes the main logic of the package/module.
Test command - Write test tool name.
Git repository - Address of git repo.
Keywords - It’s an array of strings. This helps people discover your package as it’s listed in npm search.
Author - Name of Author.
License - You should specify a license for your package so that people know how they are permitted to use it, and any restrictions you are placing on it.
Install everything in package.json:
npm install
Or use shorthand:
npm i
Install a package:
npm install <package name>
Or use shorthand:
npm i <package name>
Example:
npm install lodash
Install a package as devDependency:
npm install <package name> --save-dev
Or use shorthand:
npm install -D <package name>
Example:
npm install lodash --save-dev
Uninstalling local packages:
npm uninstall <package name> --save
Or
npm un <package name> --save
Or
npm remove <package name> --save
Or
npm rm <package name> --save
Example:
npm rm lodash --save
Install global packages:
npm install <package name> g
Uninstall global packages:
npm uninstall <package name> g
Or
npm un <package name> g
Or
npm remove <package name> g
Or
npm rm <package name> g
Example:
npm rm lodash g
Install a package based on its tag:
npm install <package name>@<tag> --save-dev
Example:
npm install lodash@latest --save-dev
Install a package to specific version:
npm install <package name>@<version> --save-dev
Example:
npm install lodash@2.1.1 --save-dev
Install a package to exact specific version:
npm install <package name>@<version> --save-exact
Example:
npm install lodash@2.4.1 --save-exact
Flags:
-P : Production (--save-prod)
-D : devDependencies (--save-dev)
-O : Optional (--save-optional)
-E : Save exact
-g : Global
-S : Save
--no-save: Prevents saving to dependencies
List locally installed packages (includes all dependencies):
npm list
Or use shorthand:
npm ls
Restrict the depth of the tree by 1:
npm list --depth 1
💡 NOTE: It gives you only immediate dependencies of the packages.
Restrict the depth of the tree by 0:
npm list --depth 0
💡 NOTE: It gives you the list of all the packages and no dependencies for that particular package.
List globally installed packages (includes all dependencies):
npm list --global
Or
npm list -g
Restrict the depth of the tree by 0 (global packages):
npm list -g --depth 0
Or
npm list --global true --depth 0
Lists the dependencies which are outdated:
npm outdated
There is a special agreement to set versions of the packages and it's called semantic versioning. It is a specification where a version is represented by three numbers that mean the same thing for every developer.
- Patch: It is used for bug fixes
- Minor: New features but compatible with previous version
- Major: Introduce non-compatible features or change your project completely
Versioning Table
Parameter | Release Version |
---|---|
Exact version | 5.21.17 |
Greater than | >5.21.1 |
Compatible changes | ^5.21.8 |
Minor-level changes | ~5.21.8 |
Version specification in package.json file (helpful when using npm install
command)
Caret (^) symbol: Stick to the given major version number but when run npm install
retrieve the latest minor and patch version.
Example:
Tilde (~) symbol: It means, leave the major version and minor version as it is but retrieve the latest version of patch number when run npm install
command.
Example:
Asterisk (*) symbol: Let's say even if there is a change in the major version number of a package but you want the latest one. In this case you will use an asterisk symbol.
So, when you specify an asterisk symbol it is going to retrieve the latest version of the package irrespective of the major minor or patch version.
Example:
No symbol: You can just have the specific version number in this case npm doesn't install a newer version even though it exists when you run npm install
.
Example:
Install specific version of a package:
npm install <package@version>
Example:
npm install lodash@3.3.0 --save
Restrict major and minor version but use patch version to latest in a package:
npm install <package@major.minor>
Example:
npm install lodash@4.14 --save
Install package only with latest major version number:
npm install <package@major>
Example:
npm install lodash@4 --save
What is the difference between package.json and package-lock.json?
When you install any package in your project by executing the command
npm install <package-name> --save
Then it will install the exact latest version of that package in your project and save the dependency in package.json with a carat (^) sign.
Like, if the current version of a package is 5.2.3 then the installed version will be 5.2.3 and the saved dependency will be ^5.2.3.
Carat (^) means it will support any higher version with major version 5 like 5.3.1 and so on. Here, package-lock.json is created for locking the dependency with the installed version.
Purpose of package-lock.json:
To avoid differences in installed dependencies on different environments and to generate the same results on every environment you should use the package-lock.json file to install dependencies.
Ideally, this file should be on your source control with the package.json file so when you or any other user will clone the project and run the command npm i
, it will install the exact same version saved in package-lock.json file and you will able to generate the same results as you developed with that particular package.
Why should you commit package-lock.json with your project source code?
During deployment, when you again run npm i
with the same package.json file without the package-lock.json, the installed package might have a higher version now from what you had intended.
Now, what if you wanted to have that particular version for your dependency during deployment which you used at the time of development. This is the need of creating a package-lock.json file and keeping it with the source code. This file is created with the details of the specific version installed in your project.
Updates all listed packages to the latest release version:
npm update
Update specific package:
npm update <package> --save
Example:
npm update lodash --save
Update only dev dependencies:
npm update --dev --save-dev
Update all the packages globally:
npm update -g
Update specific package globally:
npm update -g <package>
Example:
npm update -g lodash
Remove all unused packages(It remove modules not listed in package.json):
npm prune
More info: @stackoverflow
Dependencies:
- Installed using
npm install
ornpm install <package>
- If package A is installed using
npm install <packageA>
and it has dependency on package B then package B will be also installed along with it’s dependencies.
Development Dependencies:
- Installed using
npm install
- Not installed using
npm install --production
- If package A is installed using
npm install <packageA>
and it has devDependency on package B than package B will NOT be installed.
Install a package as devDependency:
npm install <package name> --save-dev
Or use shorthand:
npm install -D <package name>
Example:
npm install lodash --save-dev
package.json file contains dependencies and development dependencies. If you execute the npm install
command then all those dependencies will be installed in case node_modules folder is missing.
On the other hand, if you install with the production
flag then it will only install dependencies.
npm install --production
But if the package has its own development dependencies they will be never installed in your project.
💡 TIP: Do you add packages as dependency or devDependancy?
The answer is it depends: It depends on the kind of application you are developing.
If you build just a standalone application for the browser you should add all packages as development dependencies. Because browser does not understand dependencies or devDependencies.
But if you build a public package and other packages depend on your package and if you will use some functions from external packages in your compiled code then you will need to add those external packages as dependencies.
All other packages need to go into development dependencies in your project.
Print information about package:
npm view <package>
Example:
npm view lodash
Print information about package (all version):
npm view <package> versions
Example:
npm view lodash versions
To configure npm:
npm config
npm gets its config settings from the command line, environment variables, npmrc files, and in some cases, the package.json file.
Display basic configuration list:
npm config list
Display complete configuration list:
npm config list -l
Sets the config key to the value:
npm config set <key> <value>
If value is omitted, then it sets it to true
Example:
Set default author name for all new package creation:
npm config set init.author.name ‘your-name’
Verify by: npm init -y
Get default configuration value:
npm config get
Example:
Get value of default author name:
npm config get init.author.name
Edit configuration file:
npm config edit
It will opens up configuration file;
If you see carefully all new edit which you have made it reflects on top of the list.If you want to go with npm inbuilt default values then remove it and save the file.
Edit global configuration file with global values:
npm config edit --global
Delete configuration value:
npm config delete
Example:
npm config delete init.author.name
NPM scripts allow you easily perform certain operations to execute commands or execute files using npm command.
Popular npm script command:
npm start
npm run
npm built
npm start:
npm start - This runs an arbitrary command specified in the package’s “Start” property of its “scripts” object. If no “start” property is specified on the “script” object, it will run node server.js.
Project directory:
Basically what you would do is to execute node and run index.js
So let's write a script that is going to do this for us. Remove the following line from package.json file:
Now add the following line:
Now run npm start
command:
This comes in handy when you are developing a project. Let's say the project entry point is index.js.
So by having a start command the user doesn't have to worry about what command to run. So someone downloads your project from github and they run - npm start
.
Your project will automatically execute as you have intended.
Other popular npm inbuilt script command are:
npm stop
npm restart
npm test
npm prestart
npm poststart
npm prestart:
Project directory:
Install colors package as devDependency:
npm install colors --save-dev
Edit package.json file for prestart:
Now test prestart script by typing: npm start
:
Edit prestart.js file to see output in red color:
Now see the final output by typing npm start
:
NPM .bin folder with executable scripts:
During npm package installation bin scripts are copied to the .bin folder.
💡 Note: #!/usr/bin/env - Shebang line
It determines which interpreter should be used for file execution on the Unix-like operating systems. (first line in the executable plain text files)
Executes certain script:
npm run <script>
As alias of:
npm run-script <script>
npm run:
Project directory:
Edit package.json file for custom script:
Now test custom script by typing: npm start
:
Run NPM scripts simultaneously:
Install npm-run-all package:
npm i -D npm-run-all
Project directory:
Edit package.json file to run NPM scripts simultaneously:
Now run scripts simultaneously by typing: npm run all
(parallel):
If you want to run script one by one (Serial) then edit package.json file as follows:
Now run scripts simultaneously by typing: npm run all
(Serial):
NPM Shorthands: npmjs-docs