The most complete package.json analysis

1. Overview

Since we started working with the front-end, there is generally a package.json file in the root directory of each project. This file defines the various modules required for the current project, as well as the project's configuration information (such as name, version, license, etc.).

When you run the npm install command, the required modules will be automatically downloaded according to the configuration in the package.json file, that is, the running and development environment required for the configuration project.

For example, the file below only contains a simple project name and version number.

{
  "name" : "yindong",
  "version" : "1.0.0",
}

The package.json file is a JSON object, as you can see from its suffix .json. Each member of the object is a setting for the current project. For example, name is the project name and version is the version number.

Of course, many people don’t really care about the package.json configuration, they use more dependencies or devDependencies configuration.

Below is a more complete package.json file, explaining in detail what each field actually means.

{
    "name": "yindong",
    "version":"0.0.1",
    "description": "antd-theme",
    "keywords":["node.js","antd", "theme"],
    "homepage": "https://zhiqianduan.com",
    "bugs":{"url":"http://path/to/bug","email":"[email protected]"},
    "license": "ISC",
    "author": "yindong",
    "contributors":[{"name":"yindong","email":"[email protected]"}],
    "files": "",
    "main": "./dist/default.js",
    "bin": "",
    "man": "",
    "directories": "",
    "repository": {
  "type": "git",
  "url": "https://path/to/url"
 },
    "scripts": {
      "start": "webpack serve --config webpack.config.dev.js --progress"
    },
    "config": { "port" : "8080" },
    "dependencies": {},
    "devDependencies": {
        "@babel/core": "^7.14.3",
        "@babel/preset-env": "^7.14.4",
        "@babel/preset-react": "^7.13.13",
        "babel-loader": "^8.2.2",
        "babel-plugin-import": "^1.13.3",
        "glob": "^7.1.7",
        "less": "^3.9.0",
        "less-loader": "^9.0.0",
        "style-loader": "^2.0.0",
        "webpack": "^5.38.1",
        "webpack-cli": "^4.7.0",
        "webpack-dev-server": "^3.11.2"
    },
    "peerDependencies": {
        "tea": "2.x"
    },
    "bundledDependencies": [
        "renderized", "super-streams"
    ],
    "engines": {"node": "0.10.x"},
   "os" : [ "win32", "darwin", "linux" ],
    "cpu" : [ "x64", "ia32" ],
    "private": false,
    "publishConfig": {}
  }

2. Name field

The most important fields in the package.json file are name and version, which are required. The name and version together form an identifier that is considered completely unique. Changes to packages should be made together with changes to versions.
name must be less than or equal to 214 characters, cannot start with . or _, and cannot have uppercase letters. Because the name eventually becomes part of the URL, it cannot contain any non-URL-safe characters.
npm officially recommends that you do not use the same name as a core node module. Don't add js or node to the name. If necessary, you can use engines to specify the operating environment.
The name is passed as an argument to require, so it should be short but reasonably descriptive.

3. Version field

The general format of version is xxx, and this rule needs to be followed.
The most important fields in the package.json file are name and version, which are required. The name and version together form an identifier that is considered completely unique. Each time you release a version, it cannot be the same as the existing one.

4. description field

description is a string used to write description information. This helps people find your module when searching the npm repository.

5. Keywords field

keywords is an array of strings that will help people find your module when searching in the npm repository.

6. Homepage Field

homepage The homepage address of the project.

7. Bugs Field

bugs is used to report project issues using the issue address or an email address.

"bugs": { 
  "url" : "https://github.com/owner/project/issues",
  "email" : "[email protected]"
}

8. License field

The license is the agreement of the current project, which lets users know what rights they have to use your module and what restrictions there are for using the module.
"license" : "BSD-3-Clause"

9. Author Field Contributors Field

Author is a specific person, and contributors refers to a group of people, all of whom are contributors to the current project. At the same time everyone is an object. Has a name field and optional url and email fields.

"author": {
  "name" : "yindong",
  "email" : "[email protected]",
  "url" : "https://zhiqianduan.com/"
}

Can also be written as a string

"author": "yindong [email protected] (https://zhiqianduan.com/)"

10. Files Field

The value of the files attribute is an array, which contains the file name or folder name under the module. If it is a folder name, all files in the folder will also be included (unless the file is excluded by other configurations)
You can create a .npmignore file in the root directory of the module. The files written in this file will be excluded even if they are written in the files attribute. The writing method of this file is similar to .gitignore.

11. main field

The main field specifies the entry file to be loaded, and this file will be loaded when require is imported. The default value of this field is index.js in the module's root directory.

12. bin field

The bin item is used to specify the location of the executable file corresponding to each internal command. If you are writing a node tool, you will definitely use the bin field.
When we write a cli tool, we need to specify the tool's running command. For example, the commonly used webpack module, its running command is webpack.

"bin": {
  "webpack": "bin/index.js",
}

When we execute the webpack command, the code in the bin/index.js file will be executed.
The module is installed as a dependency if the bin option is present. Generate the corresponding files in node_modules/.bin/.
Npm will look for this file and create a symbolic link in the node_modules/.bin/ directory. Since the node_modules/.bin/ directory will be added to the system's PATH variable at runtime, when running npm, you can call these scripts directly through commands without the path.
All commands in the node_modules/.bin/ directory can be run using the npm run [command] format. In the command line, type npm run and then press the tab key to display all available commands.

13. man field

man is used to specify the location of the man document for the current module.

"man" :[ "./doc/calc.1" ]

14. directories field

Directories create some methods to describe the structure of the module, telling the user where each directory is located.

15. repository field

Specify a code repository address, which is helpful for people who want to contribute code to your project.

"repository" : {
  "type" : "git", 
  "url" : "https://github.com/npm/npm.git"
}

16. Scripts Field

scripts specifies the npm command line abbreviation for running script commands. For example, start specifies the command to be executed when running npm run start.

"scripts": {
  "start": "node ./start.js"
}

The scripts field can be used to quickly execute shell commands, which can be understood as alias.
Scripts can directly use modules installed in node_modules, which is different from running them directly using the npx command.

"scripts": {
  "build": "webpack"
}

// npm run build
// npx webpack

17. config field

The config field is used to add environment variables to the command line.

{
  "name" : "yindong",
  "config" : { "port" : "8080" },
  "scripts" : { "start" : "node server.js" }
}

Then, you can reference the value of the config field in the server.js script.

console.log(process.env.npm_package_config_port); // 8080

Users can modify this value via npm config set.

npm config set yindong:port 8000

18. dependencies field, devDependencies field

The dependencies field specifies the modules that the project depends on to run, and devDependencies specifies the modules required for project development.

Their value is an object. Each member of this object consists of a module name and the corresponding version requirement, indicating the dependent module and its version range.

When installing dependencies, use the --save parameter to write the module to the dependencies property, and --save-dev to write the module to the devDependencies property.

"devDependencies": {
        "webpack": "^5.38.1",
}

Each item in the object is represented by a key-value pair, with the module name in front and the version number of the corresponding module behind. The version number follows the format of "major version.minor version.small version".

Version Notes

• Fixed version: For example, 5.38.1, only the specified version is installed during installation.
• Tilde: For example, ~5.38.1, means to install the latest version of 5.38.x (not less than 5.38.1), but not 5.39.x, that is, the major and minor version numbers will not be changed during installation.
• Insert number: For example, ˆ5.38.1, means to install the latest version of 5.xx (not less than 5.38.1), but not 6.xx, that is, the major version number will not be changed during installation. It should be noted that if the major version number is 0, the behavior of the caret is the same as the tilde. This is because it is in the development stage and even minor version number changes may cause program incompatibility.
• latest: Install the latest version.

19. peerDependencies field

When we develop a module, problems will arise if the current module and the dependent module both depend on a third-party module and depend on two incompatible versions.

For example, your project depends on version 1.0 of module A and module B, and module A itself depends on version 2.0 of module B.
In most cases, this is not a problem and both versions of module B can coexist and run at the same time. However, there is a problem when this dependency is exposed to the user.

The most typical scenario is plug-in, for example, module A is a plug-in of module B. The B module installed by the user is version 1.0, but the A plug-in can only be used with version 2.0 of the B module. At this time, if the user passes an instance of version 1.0 of B to A, problems will arise. Therefore, a mechanism is needed to remind users when installing the template that if A and B are installed together, then B must be a 2.0 module.

The peerDependencies field is used for the plug-in to specify the version of the main tool it requires. You can restrict it through the peerDependencies field. The use of myless module must depend on the 3.9.x version of the less module.

{
  "name": "myless",
  "peerDependencies": {
    "less": "3.9.x"
  }
}

Note that starting with npm version 3.0, peerDependencies are no longer installed by default. It is not brought out by default during initialization.

20. bundledDependencies field

bundledDependencies specifies the modules that will be packaged together when publishing.

21. optionalDependencies field

If a dependency module can be used, and you also want npm to continue running when the module is not found or cannot be obtained, you can put this module dependency in the optionalDependencies configuration. This configuration is written in the same way as dependencies, except that a module installation failure here will not cause npm install to fail.

22. engines field

The engines field specifies the platform on which the module runs, such as a version of Node or npm or a browser.

{ "engines" : { "node" : ">=0.10.3 <0.12", "npm" : "~1.0.20" } }

23. os field

You can specify which operating systems your module can only run on

"os" : [ "darwin", "linux", "win32" ]

24. cpu field

Limit the module to run only on a certain architecture of CPU

"cpu" : [ "x64", "ia32" ]

25. Private fields

If this property is set to true, npm will refuse to publish it. This is to prevent a private module from being accidentally published.

"private": true

26. publishConfig Field

This configuration will take effect when the module is published and is used to set a set of values ​​used for publishing. If you don't want the module to be marked as the latest by default, or published to a public repository by default, you can configure the tag or repository address here.

Usually publishConfig is used with private if you only want the module to be published to a specific npm repository, such as an internal repository.

"private": true,
"publishConfig": {
  "tag": "1.0.0",
  "registry": "https://registry.npmjs.org/",
  "access": "public"
}

27. preferGlobal field

The value of preferGlobal is a Boolean value that indicates whether to display a warning when the user does not install the module as a global module (that is, without the –global parameter), indicating that the module is intended to be installed as a global module.

"preferGlobal": false

28. Browser Field

browser specifies the version of the template used by the browser. Browser packaging tools such as Browserify can help you know which file to package.

"browser": {
  "tipso": "./node_modules/tipso/src/tipso.js"
},

References

[1] npm package.json
[2] JavaScript Standard Reference Tutorial

This is the end of this article about the most comprehensive package.json parsing. For more relevant package.json parsing content, please search 123WORDPRESS.COM’s previous articles or continue to browse the following related articles. I hope everyone will support 123WORDPRESS.COM in the future!