Detailed explanation of the project directory of the Node.js package and the use of the NPM package manager_node.js

Project Directory

After understanding the above knowledge, now we can completely plan a project directory. Take writing a command line program as an example. Generally, we will provide both command line mode and API mode, and we will use third-party packages to write code. In addition to code, a complete program should also have its own documentation and test cases. Therefore, a standard project directory looks like the following.

- /home/user/workspace/node-echo/  # 工程目录
  - bin/             # 存放命令行相关代码
    node-echo
  + doc/             # 存放文档
  - lib/             # 存放API相关代码
    echo.js
  - node_modules/         # 存放三方包
    + argv/
  + tests/            # 存放测试用例
  package.json          # 元数据文件
  README.md            # 说明文件

The contents of some of the files are as follows:

/* bin/node-echo */
var argv = require('argv'),
  echo = require('../lib/echo');
console.log(echo(argv.join(' ')));

/* lib/echo.js */
module.exports = function (message) {
  return message;
};

/* package.json */
{
  "name": "node-echo",
  "main": "./lib/echo.js"
}

In the above example, different types of files are stored in categories, and modules are loaded directly using third-party package names through the node_moudles directory. In addition, after defining package.json, the node-echo directory can also be used as a package.

NPM

NPM is a package management tool installed along with NodeJS. It can solve many problems in NodeJS code deployment. Common usage scenarios include the following:

• Allow users to download third-party packages written by others from the NPM server for local use.
• Allows users to download and install command line programs written by others from the NPM server for local use.
• Allows users to upload packages or command line programs they write to the NPM server for others to use.

As you can see, NPM has established a NodeJS ecosystem, where NodeJS developers and users can communicate with each other. The following describes how to use NPM in these three scenarios.

Download third-party packages
When you need to use third-party packages, you must first know which packages are available. Although npmjs.org provides a search box to search based on the package name, if you are not sure about the name of the third-party package you want to use, please ask Baidu. After knowing the package name, such as argv in the above example, you can open the terminal in the project directory and use the following command to download the third-party package.

$ npm install argv
...
argv@0.0.2 node_modules\argv

After downloading, the argv package is placed in the node_modules directory under the project directory, so you only need to require('argv') in the code without specifying the third-party package path.

The above command downloads the latest version of the third-party package by default. If you want to download a specific version, you can add @ after the package name. For example, you can download version 0.0.1 of argv through the following command.

$ npm install argv@0.0.1
...
argv@0.0.1 node_modules\argv

If you use a lot of third-party packages, it would be too cumbersome to install each package with one command in the terminal. Therefore, NPM has extended the fields of package.json to allow third-party package dependencies to be declared in it. Therefore, package.json in the above example can be rewritten as follows:

{
  "name": "node-echo",
  "main": "./lib/echo.js",
  "dependencies": {
    "argv": "0.0.2"
  }
}

After processing in this way, you can use the npm install command to batch install third-party packages in the project directory. More importantly, when node-echo is also uploaded to the NPM server in the future and others download this package, NPM will automatically download further dependent third-party packages based on the third-party package dependencies declared in the package. For example, when using the npm install node-echo command, NPM automatically creates the following directory structure.

- project/
  - node_modules/
    - node-echo/
      - node_modules/
        + argv/
      ...
  ...

In this way, users only need to care about the third-party packages they use directly, and do not need to resolve the dependencies of all packages themselves.

Install command line program
The method of downloading and installing a command line program from the NPM service is similar to that of third-party packages. For example, node-echo in the above example provides a command line usage method. As long as node-echo has configured the relevant package.json fields, users only need to use the following command to install the program.

$ npm install node-echo -g

The -g in the parameter indicates global installation, so node-echo will be installed to the following location by default, and NPM will automatically create the soft link file required under Linux systems or the .cmd file required under Windows systems.

- /usr/local/        # Linux系统下
  - lib/node_modules/
    + node-echo/
    ...
  - bin/
    node-echo
    ...
  ...

- %APPDATA%\npm\      # Windows系统下
  - node_modules\
    + node-echo\
    ...
  node-echo.cmd
  ...

Post code
You need to register an account before using NPM to publish code for the first time. Run npm adduser in the terminal, and then follow the prompts. After the account is set up, we then need to edit the package.json file and add the required fields for NPM. Following the node-echo example above, the necessary fields in package.json are as follows.

{
  "name": "node-echo",      # 包名，在NPM服务器上须要保持唯一
  "version": "1.0.0",      # 当前版本号
  "dependencies": {       # 三方包依赖，需要指定包名和版本号
    "argv": "0.0.2"
   },
  "main": "./lib/echo.js",    # 入口模块位置
  "bin" : {
    "node-echo": "./bin/node-echo"   # 命令行程序名和主模块位置
  }
}

After that, we can run npm publish in the directory where package.json is located to publish the code.

Version number
When you use NPM to download and publish code, you will come into contact with the version number. NPM uses semantic version numbers to manage code. Here is a brief introduction.

The semantic version number is divided into three digits: X.Y.Z, which represent the major version number, minor version number and patch version number respectively. When the code changes, the version number is updated according to the following principles.

+ If you just fix the bug, you need to update the Z bit.

+ If a new function is added, but it is backward compatible, the Y bit needs to be updated.

+ If there are major changes, it is not backward compatible and X bit needs to be updated.
After the version number has this guarantee, when declaring third-party package dependencies, in addition to relying on a fixed version number, it can also rely on a certain range of version numbers. For example, "argv": "0.0.x" means that it depends on the latest version of argv in the 0.0.x series. For all version number range specification methods supported by NPM, please view the official documentation.

Be clever
In addition to the parts introduced in this chapter, NPM also provides many functions, and there are many other useful fields in package.json. In addition to viewing the official documentation at npmjs.org/doc/, here are some common NPM commands.

NPM provides many commands, such as install and publish. Use npm help to view all commands.

• Use npm help to view detailed help for a command, such as npm help install.
• Use npm install . -g in the directory where package.json is located to install the current command line program locally first, which can be used for local testing before release.
• Use npm update to update the corresponding modules in the node_modules subdirectory in the current directory to the latest version.
• Use npm update -g to update the corresponding command line program installed globally to the latest version.
• Use npm cache clear to clear the NPM local cache, which is used to deal with people who use the same version number to release new versions of code.
• Use npm unpublish @ to unpublish a version of code you have published.