A prelude to

Package. json is the most common configuration file that we deal with in our work. It helps users of the NPM package to better understand and use the NPM package. Cherie went through the configuration of package.json in detail.

Must attribute

name

Name is the unique identifier of a package. It must contain a maximum of 214 characters and cannot start with. Cannot contain uppercase letters and _.

You can run the NPM view packageName command to check whether the packageName is occupied.

version

The format is the major version number. Second version number. The form of revision number. If it is unstable, you can send internal version (alpha), public beta version (beta), candidate version (RC) (2.0.1-alpha). Those of you who have been involved in building in-house component libraries know this.

Description information

description

This field describes the project as a string.

keywords

This field describes the keywords of the project as an array of strings.

{
  "keywords": ['lint', 'react','ts']
}
Copy the code

Good description and keywords will give our NPM package more exposure.

author

Describes the NPM package author.

  {
   "author":'xiaoqi'
   / / or
   "author": {
     "name" : "xiaoqi"."email" : "[email protected]"."url" : "https://juejin.cn/user/1275089220808040"}}Copy the code

contributors

Describe the project contributors. Unlike author, it is an array.

homepage

Describes the home page address of the project as a string.

repository

Describes the code repository address.

{
  "repository": "https://github.com/facebook/react.git"
  / / or
  "repository": {
    "type": "git"."url": "https://github.com/facebook/react.git"}}Copy the code

bugs

Describes the address of the project submission problem.

{
 "bugs": { 
    "url" : "https://github.com/facebook/react/issues"."email" : "[email protected]"}}Copy the code

Depend on the configuration

Note: Declaring packages in Dependencies and devDependencies has nothing to do with the packaging tool not packaging them.

Dependencies:

Declare the dependency packages that the project will need in production. Before installing a dependency package, determine whether it is required in the production environment.

NPM I XXX or NPM I XXX --save or NPM I XXx-sCopy the code

This value is an object that records the name and version number of the dependent package.

Dependencies: {" CLSX ":" 1.1.1 "swiper" : "" ^ 6.4.8"}Copy the code

As mentioned earlier, the version number generally follows the major version number. Second version. Revision number. When we install the NPM package, we come across several versions of it.

  • Latest: Installs the latest version

  • ^: For example, install the latest version of 6.x.x as described above, but not less than 6.4.8. This form is the one that Xiao Qi sees most frequently in the projects she develops.

  • ~ : For example, ~6.4.8. Indicates to install the latest 6.4.x version, but not less than 6.4.8.

  • Fixed version number

CLSX above is the fixed version number. Sometimes you can specify a fixed stable version to install when the latest version of a dependency package is problematic.

devDependencies

Declare dependency packages that the project will need only at development time. Eslint, typescript, Vite, prettier are ancillary packages used for development and not needed in production.

If the current project is referenced as a dependency package, the package in devDependencies is not installed when NPM install — Production is used.

NPM I XXX --save-dev or NPM I XXX -dCopy the code
dependencies: {
    "eslint": "latest"."typescript": "^ 4.4.4." "
}
Copy the code

peerDependencies

The scenario is typically a plug-in or component library.

For example, when we need to implement A function in project A (main project) and this function is relatively independent and complex, we can take this part of the function out and create A new project B to maintain it, and introduce project B (dependent project) in the form of dependency package in project A. It’s the same way we introduce someone else’s LIBRARY of UI components into our project.

What problem does peerDependencies help us solve?

Avoid the problem of project A installing A version inconsistent with the core package that Project B relies on

For example, project B must install React and react-dom and must run at least 16.8.0. Otherwise, an error will be reported. If the react/act-DOM dependency packages are not installed in project A or A lower version is installed, an error will occur.

 "peerDependencies": {
    "react": "> = 16.8.0"."react-dom": "> = 16.8.0"
  }
Copy the code

We add the peerDependencies field in the package.json file of project B and declare the dependent core package and version number (the peerDependencies field is not declared in dependencies and can be ignored if it is declared). This tells project A: “If you want to install me, you must install the react and react-dom packages at A version larger than 16.8.0, or you may get an error.”

When Writing business, if project A is large enough, project A will install the packages that project B’s production environment depends on. Then, She will write these dependency packages into the peerDependencies field, which does not declare these dependency packages and directly asks project A to install them.

bundledDependencies

You can declare dependencies in bundledDependencies if you want certain dependencies to be packaged with them when they are published. Note that these packages are declared in dependencies in advance.

{" name ":" my_test ", "version" : "1.0.0", "bundledDependencies" : [" react ", "the react - dom"],}Copy the code

After NPM pack, my_test-1.0.0.tgz is generated. NPM install my_test-1.0.0.tgz. NPM install my_test-1.0.0.tgz.

optionalDependencies

Another kind of dependencies. If NPM fails to install dependencies, it does not interrupt the installation of the module declared in optionalDependencies. OptionalDependencies overwrites dependencies of the same name and does not need to be declared in both places.

engines

Describes the environment in which the module runs. This scenario is suitable for maintenance of older projects, such as those that require both node and NPM versions to run otherwise. After being declared in Engines, developers are reminded to upgrade to the specified version.

"engines": {
    "node": ">= 11"
    "npm": "~6.0.1"
  }
Copy the code

The script configuration

scripts

The abbreviation used to configure the command to run the script.

"scripts": {
  "dev": "node index.js",
}
Copy the code

This can be done with NPM run dev. The advantage of this field is that it greatly improves development efficiency.

config

Configure the environment variables used in the script.

{
  "name" : "my_test",
  "config": {"port": 3000}
}
Copy the code

Then you can use process.env.npm_package_config_port in your scripts to get this value. We can modify this value with a nom config set.

npm config set my_test:port 8000
Copy the code

Directories and files are related

files

This field represents, as an array, the list of files pushed when the NPM package is published.

{
    "files": [
      "dist",
      "lib",
      "es"
    ]
}
Copy the code

If some files do not want to be published, you can configure a. Npmignore file in the root directory to exclude some files (similar to the.gitignore file), even if the file name is written in the files field, it will not be published. If there is a.gitignore file, the.npmignore file will be used instead.

main

Specifies the entry file that the program loads, which is available in both Browser and Node environments. This field is not specified; the default is the index.js file in the root directory. If our package is installed as an NPM, then require importing the NPM package is actually the module exposed in the module.export file specified by the mian field.

"main": "./src/index.js"
Copy the code

browser

If the NPM package is only available on the Browser side, have the Browser field specify the entry file instead of the main field.

{
   "browser": "./src/index.js" 
}

Copy the code

bin

Specifies the entry file for the command line tool. This field is often used when writing Node tools, such as common CLI tools. For example, there is now a my-CLI tool with the bin field in package.json:

{
 "bin": {
    "my-cli": "./bin/index.js"}}Copy the code

When we execute the my-cli command we execute the code in the bin/index.js file.

If the my-cli package is installed globally, a symlink named my-cli will be created in /usr/local/bin, pointing to the /bin/index.js file of the my-cli package. You can run the my-cli command directly.

If the my-cli package is installed locally, the symlink named my-cli will be created under node_modules/. Bin and the /bin/index.js file of the my-cli package will be executed. Since node_modules/.bin/ adds the PATH variable to the system at runtime, you can run it directly using NPM run my-cli. (All commands in node_modules/. Bin/can be run in NPM run xx format.)

man

Used for Linux man command to find the document address, is a single file or file array. The man file must end with a number, or.gz if compressed. The numbers indicate which part of man the file will be installed into.

{
  "name": "my_test"."version": "1.1.0"."description": ""."main": "index.js"."man": "./man/doc.1"
}
Copy the code

The contents of the./man/doc.1 file can be obtained by using the man my_test command.

directories

This field is used to standardize the project’s catalog. A Node module is implemented based on the CommonJS modular specification. In strict accordance with the CommonJS modular specification, the project directory must contain the following directories in addition to the package.json file:

  • Bin: directory for storing executable binary files

  • Lib: the directory for storing JS code

  • Doc: directory for storing documents

  • Test: Directory for storing unit test case code

    .

In the case of a real project where you might not strictly follow the above specifications, use the Directories field to specify how the project’s directory structure corresponds to the above specifications.

 "directories": {
    "lib": "src/lib/"."bin": "src/bin/"."man": "src/man/",}Copy the code

Release configuration

preferGlobal

If your NPM package requires a global installation, you can set this field to true to warn users if they install it locally.

private

Setting private to true prevents publishing private libraries to the NPM server.

{
  "private": true
}
Copy the code

If you only want to publish the package to a private NPM source or only want to publish a tag, you can configure the information with the publishConfig field.

publishConfig

{
    "private": true."publishConfig": {
      "tag": "1.1.0"."registry": "https://registry.npmjs.org/"."access": "public"}}Copy the code

More configuration npm.config

os

This field tells the user what operating system the NPM package can be used on.

"OS ": [" Linux "]" OS ": ["! Win32 "] // Disable Win32Copy the code

cpu

Similar to the OS, CPU attributes can be used to more accurately inform the user about the CPU environment in which the package is being used.

"cpu" : [ "x64", "ia32" ]
Copy the code

license

Used to specify the open source protocol. The different protocols represent the rights that the person who uses your code has. Authors can choose the appropriate protocol according to their own works, which permissions to open for users.

"license": "MIT"
Copy the code
  • MITAs long as the user includes the copyright notice and license notice in the project copy, they can do whatever they want with your code without any liability on your part.
  • Apache: similar toMIT, it also contains provisions for contributors to provide patent licenses to users.
  • GPLUsers who modify project code must publish their changes when they redistribute source code or binary code.

Third-party Configuration

There are other commonly used fields: Typings, eslintConfig, gitHooks, Lint-staged, etc., but non-staged fields are not expanded here.

The end of the

Refer to the article

  • npm
  • What do you know about package.json?