What Does NPM Do?
Just like RubyGems from Ruby or Maven from Java, Node.js also has a package manager, Node Package Manager (NPM) . It has become so popular throughout the community that beginning with the 0.6.X Node.js version it was integrated within the main Node.js installer, becoming the standard manager of this platform. This helped the developers at that time, because it made several projects converge to this tool.
Nowadays, the NPM home page , shown in Figure 3-1, hosts more than 350k of modules created and there are 4 million developers and thousands of companies using this platform.
Figure 3-1. The NPM home page at npmjs.org
Top NPM Commands
NPM is very easy to use. You can use it to manage your project’s dependencies, and when you create commands for task automation purposes, everything is created and managed into the package.json file. The following are the top NPM commands.
npm init: Displays a simple wizard to help you create and describe your new project.
npm install module_name: Installs a module.
npm install -g module_name: Install a global module.
npm install module_name --save: Installs a module and adds it into the package.json file, inside dependencies.
npm install module_name --save-dev: Installs a module and adds it into the package.json file, inside devDependencies.
npm list: Lists all the modules installed on the project.
npm list -g: Lists all the global modules installed on the OS.
npm remove module_name: Uninstalls a module from the project.
npm remove -g module_name: Uninstalls a global module.
npm remove module_name --save: Uninstalls a module from the project and also removes it from the attribute dependencies.
npm remove module_name --save-dev: Uninstalls a module from the project and also removes it from the attribute devDependencies.
npm update module_name: Updates the module version.
npm update -g module_name: Updates the global module version.
npm -v: Displays the NPM current version.
npm adduser username: Creates an account to https://npmjs.org .
npm whoami: Displays details of your public NPM profile (you must create an account using the previous command).
npm publish: Publishes a module to npmjs.org (it’s necessary to have an active account first ).
Understanding the package.json File
All Node.js projects are called modules. What is a module ? Throughout the book, note I use the terms module, library, and framework. In practice, they all mean the same thing.
The term module was taken from JavaScript’s concept, which is a language that works with a modular architecture. When we create a Node.js project (i.e., a module), this project is followed by a descriptor file of modules, called package.json.
This file is essential to a Node.js project. A badly written package.json can cause bugs or even prevent your project from executing, because this file has some key attributes that are read by both Node.js and the NPM .
To demonstrate it, here is a simple example of a package.json file that describes the main attributes of a module:
1 {2 "name": "my-first-node-app",3 "description": "My first node app",4 "author": "User <[email protected]>",5 "version": "1.2.3",6 "private": true,7 "dependencies": {8 "module-1": "1.0.0",9 "module-2": "∼1.0.0",10 "module-3": ">=1.0.0"11 },12 "devDependencies": {13 "module-4": "*"14 }15 }
With those few attributes, you are able to describe your module. The attribute name is the main one, as it defines a programmatic name of the project. This module name will be called via the require("my- first-node-app") function. It must be written in a clean and short way, offering an abstract about the module will be.
The author attribute is provides the name and e-mail of the author. You can use the format Name <email> so that web sites, such as npmjs.org , can read this information correctly.
Another main attribute is the version, which defines the current version of the module. It is highly recommended that you use this attribute to allow a module installation via the npm install my-first-node-app command. The attribute private is optional; it is only a boolean that determines if the project is an open source or a private project.
Node.js modules work with three levels of versioning. For example, the version 1.2.3 is divided into the following levels:
Major: X.0.0
Minor: 0.X.0
Patch: 0.0.X
Note the X means the current level version to date.
The previous package.jsonhas four modules, and each one uses a different semantic version. The first one, "module-1", has a fixed version 1.0.0. Use this kind of version to install dependencies with updates that can break the project if you change the version.
The next module, "module-2", already has a certain update flexibility. It uses the character "∼", which allows you to update a module as a patch level 1.0.x (it only updates the x version). Generally, these updates are safe, as they bring improvements and bug fixes.
The "module-3" updates versions that are greater than or equal to 1.0.0 in all the version levels. In many cases, using ">=" can be risky, because the dependency can be updated to a major or minor level and, consequently, can bring some modifications that can break your application.
The last one, "module-4", uses the "*" character. This one always catches the latest version of the module in any version level. It also can cause trouble in the updates and it has the same behavior as the module-3 versioning. Generally, it is used only in the devDependencies, which are dependencies used for test purposes that do not affect the application behavior. Do not use this kind of version in a production environment!
If you want to have more precise control over the versions of your dependencies after their installation in your project, run the npm shrinkwrap command. It will lock all dependencies versions within the file npm-shrinkwrap.jsongiving you control over the dependencies versions of your project. This command is very useful in a production environment, where the versions need to be stricter.
NPM Task Automation
You can also automate tasks using the npm command. In practice, you can only create new executable commands running npm run command_name. To declare those new commands, just create them inside the attribute scripts on package.jsonas in this example.
1 {2 "name": "my-first-node-app",3 "description": "My first node app",4 "author": "User <[email protected]>",5 "version": "1.2.3",6 "private": true,7 "scripts": {8 "start": "node app.js",9 "clean": "rm -rf node_modules",10 "test": "node test.js"11 },12 "dependencies": {13 "module-1": "1.0.0",14 "module-2": "∼1.0.0",15 "module-3": ">=1.0.0"16 },17 "devDependencies": {18 "module-4": "*"19 }20 }
Note that this new package.jsoncreated three scripts: start, clean, and test. These scripts are executable now via their commands: npm run start, npm run clean, and npm run test. As a shortcut, only the start and test commands can be executed by the alias: npm start and npm test. Within the scripts, you can run the command node, npm or any other global command from the OS. The npm run clean command is an example of a global command from the bash, which internally runs the command rm -rf node_modules to delete all files from the node_modules folder.
Conclusion
At this point, you have learned the basics about managing dependencies and automating tasks using NPM. It is important to understand these concepts because they are used frequently throughout this book.
Fasten your seatbelts and get ready! In the next chapter we are going to start our API RESTful pilot project, which is going to be worked on throughout the next chapters. As a spoiler, I am going to tell you what this project will be.
In the next chapters, we are going to create a simple API REST system to manage tasks. In addition to the API, we’ll also create a web application to consume data from this API. All development is going to happen using popular Node.js frameworks: Express to create the API resources, Sequelize to persist data in a relational database, Passport to deal with user authentications, and many more.