Front-end JavaScript housekeeper package.json

Preface:

Today, let's take a look at the configurations of the front-end package.json file. A full understanding of these configurations will help us improve development efficiency and standardize our projects. The article contains a lot of content, so it is recommended that you save it for study first!

In every front-end project, there is a package.json file, which is the configuration file of the project. Common configurations include configuring project startup, packaging commands, declaring dependent packages, etc. The package.json file is a JSON object, each member of which is a setting for the current project. As the steward of the front-end, what configurations of package.json are closely related to our daily development? Let's take a closer look at this file.​

When we build a new project, the scaffolding often helps us initialize a package.jaon configuration file, which is located in the root directory of the project. When a project is initialized using the react scaffold (create-react-app), the contents of its package.json file are as follows:

{
  "name": "my-app",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@testing-library/jest-dom": "^5.14.1",
    "@testing-library/react": "^11.2.7",
    "@testing-library/user-event": "^12.8.3",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "react-scripts": "4.0.3",
    "web-vitals": "^1.1.2"
  },
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ]
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

When we clone a new project locally, we need to execute npm install (yarn install) command to install the dependency files required by the project. When this command is executed, the required modules will be automatically downloaded according to the configuration information in the package.json file, that is, the running and development environment required for the configuration project.​

Common configuration items in package.json are as follows:

1. Required attributes

The two most important fields in package.json are name and version . They are both required. Without them, the npm install command cannot be executed normally. npm specifies that the package.json file uses the name and version number as a unique identifier.

1. name

name is easy to understand, it is the name of the project, it is a string.

When naming the name field, you need to pay attention to the following points:

• The name must be less than or equal to 214 characters long, cannot start with "." or "_", and cannot contain uppercase letters (this is because when the package is published on npm , it will get its own URL based on this property, so it cannot contain non-url-safe );
• The name can be passed as an argument require ("") to import the module, so it should be as short and semantic as possible;
• The name cannot be the same as that of other modules. You can use npm view command to check whether the module name is repeated. If not, a 404 error message will be displayed:
  

If there is a corresponding package on the npm package, the detailed information of the package will be displayed:

In fact, many of the projects we develop are not published on npm , so whether the name is standard may not be so important, and it will not affect the normal operation of the project. If you need to publish it on npm , the name field must meet the requirements.

2. version

version field indicates the version number of the project package, which is a string. After each project change, when it is about to be released, the project version number must be changed synchronously.

The version number usage specifications are as follows:

• The version number is named according to the Semantic Versioning 2.0.0 specification, in the format of major version number.minor version number.revision number. Usually, changing the major version number means making a major functional change, changing the minor version number means adding new features, and changing the revision number means fixing some bugs.
• If a version has major changes and is unstable, and may not meet the expected compatibility requirements, it is necessary to release a pre-release version. The pre-release version will be added after the version number, and the dot-separated identifier and version compilation information will be connected by a "-" sign: internal version (alpha), public beta version (beta) and candidate version (rc, release candiate).
  

You can view the version information of the npm package by using the following command, taking react as an example:

// View the latest version npm view react version
// View all versions npm view react versions

When the second command is executed, the result is as follows:

2. Description Information

There are five configuration fields in package.jaon that are related to the project package description information. Let's take a look at the meanings of these fields respectively.

1. description

The description field is used to describe this project package. It is a string that allows other developers to find our project package in npm search.

2. keywords

keywords field is a string array representing the keywords of this project package. Like description , it is used to increase the exposure of the project package.

Below is the description and keywords of the eslint package:

3. author

author as the name implies, is the author, indicating the author of the project package. It has two forms, one is string format:

"author": "CUGGZ <[email protected]> (https://juejin.cn/user/3544481220801815)"

The other is the object form:

"author": {
  "name" : "CUGGZ",
  "email" : "[email protected]",
  "url" : "https://juejin.cn/user/3544481220801815"
}

4. Contributors

contributors represents the contributors of the project package. Unlike author, this field is an array containing all contributors. It also has two ways of writing:

"contributors": [
  "CUGGZ0 <[email protected]> (https://juejin.cn/user/3544481220801815)",
  "CUGGZ1 <[email protected]> (https://juejin.cn/user/3544481220801815)"
 ]

"contributors": [
  {
   "name" : "CUGGZ0",
   "email" : "[email protected]",
   "url" : "https://juejin.cn/user/3544481220801815"
 },
  {
   "name" : "CUGGZ1",
   "email" : "[email protected]",
   "url" : "https://juejin.cn/user/3544481220801815"
 }
 ]

5. Homepage

homepage is the homepage address of the project, which is a string.

6. repository

repository represents the address of the repository where the code is stored, and is usually written in two forms. The first is in string form:

"repository": "https://github.com/facebook/react.git"

In addition, you can also explicitly set the version control system, in this case in the form of an object:

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

7. Bugs

bugs represents the address for submitting issues in the project. This field is an object that can add an address for submitting issues and an email address for feedback:

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

The most common bugs are on the issues page in Github . The above is the address of react 's issues page.

3. Dependency Configuration

Usually, our project will depend on one or more external dependency packages. Depending on the different uses of the dependency packages, they can be configured under the following five properties: dependencies , devDependencies , peerDependencies , bundledDependencies , optionalDependencies . Let's take a look at the meaning of each attribute.

1. dependencies

The dependencies field declares the required dependency packages for the project's production environment. When you install an npm package using npm or yarn , the npm package will be automatically inserted into this configuration item:

npm install <PACKAGENAME>
yarn add <PACKAGENAME>

When you use the --save parameter when installing dependencies, the newly installed npm packages will also be written to dependencies property.

npm install --save <PACKAGENAME>

The value of this field is an object whose members consist of module names and corresponding version requirements, indicating the dependent modules and their version ranges.

"dependencies": {
   "react": "^17.0.2",
   "react-dom": "^17.0.2",
   "react-scripts": "4.0.3",
},

Each configuration here is a key-value value), key represents the module name, and value represents the version number of the module.

The version number follows the format of major version number.minor version number.revision number:

• Fixed version: The react-scripts version 4.0.3 above is a fixed version. Only this specified version is installed during installation;
• Tilde: For example, ~4.0.3 means installing the latest version of 4.0.x (no less than 4.0.3), which means that the major and minor version numbers will not be changed during installation;
• Insert number: For example, the react version ^17.0.2 above means installing the latest version of 17.xx (not less than 17.0.2), which means that the major version number will not be changed during installation. If the major version number is 0, then the behavior of the caret and tilde characters is the same;
• latest: Install the latest version.
• It is important to note that you should not put test or transitional dependencies in dependencies to avoid unexpected problems in the production environment.

2. devDependencies

devDependencies declares the dependency packages required during the development phase, such as Webpack , Eslint , Babel , etc., to assist in development. They differ from dependencies in that they only need to be installed on your development machine and are not required to run your code in production. These packages are not needed when packaging and launching, so you can add these dependencies to devDependencies . These dependencies will still be installed and managed when you specify npm install locally, but they will not be installed in the production environment.

When installing packages using npm or yarn , the newly installed npm packages will be automatically inserted into this list by specifying the following parameters:

npm install --save-dev <PACKAGENAME>
yarn add --dev <PACKAGENAME>

"devDependencies": {
  "autoprefixer": "^7.1.2",
  "babel-core": "^6.22.1"
}

3. peerDependencies

In some cases, our project and the modules it depends on will both depend on another module, but the versions they depend on are different. For example, our 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 simultaneously. 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 plugin to specify the version of the main tool it requires.

"name": "chai-as-promised",
"peerDependencies": {
   "chai": "1.x"
}

The above code specifies that when installing the chai-as-promised module, the main program chai must be installed together, and the version of chai must be 1.x. If the project specifies a dependency of version 2.0 of chai, an error will be reported.

Note that starting with npm version 3.0, peerDependencies are no longer installed by default.

4. optionalDependencies

If you need npm to continue running when the package cannot be found or the installation of the package fails, you can put the package in the optionalDependencies object. The packages in the optionalDependencies object will override the packages with the same name in dependencies , so you only need to set it in one place.

It should be noted that since the dependencies in optionalDependencies may not be installed successfully, exception handling must be done, otherwise an error will be reported when obtaining this dependency if it cannot be obtained.

5. bundledDependencies

The above dependency-related configuration items are all objects, while the bundledDependencies configuration item is an array, in which you can specify some modules that will be packaged together when this package is released.

It should be noted that the values ​​in this field array must be packages declared in dependencies and devDependencies .

6. engines

When we maintain some old projects, we may have special requirements for npm package version or Node version. If the conditions are not met, the project may not be able to run. In order for the project to work out of the box, you can specify the specific version number in the engines field:

"engines": {
 "node": ">=8.10.3 <12.13.0",
  "npm": ">=6.9.0"
}

Note: engines only serves as an explanation. Even if the version installed by the user does not meet the requirements, it will not affect the installation of dependent packages.

4. Script Configuration

1. Scripts

scripts is a built-in script entry in package.json . It is key-value pair configuration. The key is an executable command that can be executed through npm run. In addition to running basic scripts commands, you can also combine pre and post to complete pre- and post-operations.

Let's look at a set of scripts first:

"scripts": {
 "dev": "node index.js",
  "predev": "node beforeIndex.js",
  "postdev": "node afterIndex.js"
}

There is a console in each of these three js files:

// index.js
console.log("scripts: index.js")
// beforeIndex.js
console.log("scripts: before index.js")
// afterIndex.js
console.log("scripts: after index.js")

When we execute the npm run dev command, the output is as follows:

scripts: before index.js
scripts: index.js
scripts: after index.js

As you can see, all three commands are executed, and the execution order is predev→dev→postdev . If scripts commands have a certain sequence, you can use these three configuration items to configure the execution commands separately.

By configuring the scripts property, you can define some common operation commands:

"scripts": {
  "dev": "webpack-dev-server --inline --progress --config build/webpack.dev.conf.js",
  "start": "npm run dev",
  "unit": "jest --config test/unit/jest.conf.js --coverage",
  "test": "npm run unit",
  "lint": "eslint --ext .js,.vue src test/unit",
  "build": "node build/build.js"
}

These scripts are command-line applications. They can be run by calling npm run XXX or yarn XXX , where XXX is the name of the command. For example: npm run dev . We can use any name for the command, and the script can be anything.

Using this field properly can greatly improve development efficiency.

2. config

The config field is used to configure the configuration parameters of scripts runtime, as shown below:

"config": {
 "port": 3000
}

If you run npm run start , the port field is mapped to npm_package_config_port environment variable:

console.log(process.env.npm_package_config_port) // 3000

Users can override the port value by running npm config set foo:port 3001 command.

5. Files & Directories

Let's take a look at the properties related to files and directories in package.json .

1. main

The main field is used to specify the entry file to be loaded, which can be used in both browser and Node environments. If we publish the project as an npm package, when we use require to import the npm package, what is returned is module.exports property of the file listed in the main field. If this field is not specified, the default is index.js in the project root directory. If not found, an error will be reported.​

The value of this field is a string:

"main": "./src/index.js",

2. browser

browser field can define the entry file of npm package in browser environment. If the npm package is only used on the web side and is strictly prohibited from being used on the server side, use browser to define the entry file.

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

3. module

module field can define the ESM specification entry file of the npm package, which can be used in both browser environment and node environment. If the npm package exports an ESM-compliant package, use module to define the entry file.

"module": "./src/index.mjs",

Note: .js files use the commonJS standard syntax (require('xxx')) , and .mjs files use the ESM standard syntax (import 'xxx').​

The configurations of the above three entry files are different, especially in different usage scenarios. In a web environment, if you use loader to load ESM (ES module), the loading order of these three configurations is browser→module→main . If you use require to load CommonJS modules, the loading order is main→module→browser .​

When Webpack is building a project, there is a target option, which defaults to Web, that is, building a Web application. If you need to compile some isomorphic projects, such as node projects, you only need to set the target option of webpack.config.js to node for building. If you load CommonJS modules or ESM in a Node environment, only the main field is valid.

4. bin

The bin field is used to specify the location of the executable file corresponding to each internal command:

"bin": {
  "someTool": "./bin/someTool.js"
}

Here, the executable file corresponding to the someTool command is someTool.js in the bin directory, someTool.js will create a symbolic link node_modules/.bin/someTool . Since 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. Therefore, the following can be shortened:

scripts: {  
  start: './node_modules/bin/someTool.js build'
}

// Shorthand scripts: {  
  start: 'someTool build'
}

All commands in node_modules/.bin/ directory can be run using npm run [command] format.

The above configuration provides a bin field in package.json that maps to a local file name. The npm package will then link this file to prefix/fix for global import. Or link to your local node_modules/.bin/ file for use in this project.

5. files

The files configuration is an array that describes the list of files that need to be specified when installing npm package as a dependency package. When the npm package is published, the files specified by files will be pushed to npm server. If a folder is specified, all files under the folder will be submitted.

"files": [
    "LICENSE",
    "Readme.md",
    "index.js",
    "lib/"
 ]

If there are files that you do not want to submit, you can create a new .npmignore file in the project root directory and describe the files that do not need to be submitted to prevent junk files from being pushed to npm . The format of this file is similar to .gitignore . Files written to this file will be excluded even if they are written in the files attribute. For example, you can write in this file:

node_modules
.vscode

build

.DS_Store

6. man

The man command is a help command in Linux. Through this command, you can view information such as command help, configuration file help, and programming help in Linux. If node.js module is a global command line tool, you can specify the document address that the man command searches for in package.json through the man attribute:

"man": [
 "./man/npm-access.1",
 "./man/npm-audit.1"
]

The man field can specify one or more files. When man {package name} is executed, the document content will be displayed to the user.

Note:

• The man file must end with a number and can use the .gz suffix if it is compressed. This number indicates which man section the file is installed into; if the man file name does not begin with the module name, the module name prefix is ​​added when it is installed.
  

For the above configuration, you can use the following command to view the document:

man npm-access
man npm-audit

7. Directories

The directories field is used to specify the project directory. Node.js modules are implemented based on CommonJS modularization specification and need to strictly follow the CommonJS specification. In addition to the package project description file package.json , the module directory must also contain the following directories:

• bin: directory for storing executable binary files
• lib: directory where js code is stored
• doc: directory for storing documents
• test: Directory for storing unit test case codes
• ...
  

In the actual project directory, we may not name it according to this specification, so we can specify the file path corresponding to each directory in directories field:

"directories": {
    "bin": "./bin",
    "lib": "./lib",
    "doc": "./doc",
    "test" "./test",
    "man": "./man"
},

This attribute actually has no practical use, but it is not ruled out that it will have some more meaningful uses in the future.

6. Release Configuration

Let's take a look at the configuration related to npm project package release.

1. private

The private field prevents us from accidentally publishing private libraries to the npm server. Just set this field to true:

"private": true

2. preferGlobal

The preferGlobal field indicates that when the user does not install the module as a global module, a warning will be displayed if it is set to true. It does not actually prevent users from performing partial installations, but only provides a reminder to prevent misunderstandings:

"preferGlobal": true

3. publishConfig

The publishConfig configuration takes effect when the module is published and is used to set a collection of configuration items when publishing. If you don't want the module to be marked as the latest by default, or don't want to publish it to a public repository, you can configure the tag or repository address here. For more detailed configuration, please refer to npm-config .​

Normally, publishConfig is used with private . If you only want the module to be published to a specific npm repository, you can configure it like this:

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

4. os

The os field allows us to set which operating systems the npm package can and cannot be used on. If we want to develop an npm package that only runs on Linux, in order to avoid unnecessary exceptions, it is recommended that users using Windows systems do not install it. In this case, you can use the os configuration:

"os" ["linux"] // Applicable operating systems "os" ["!win32"] // Disabled operating systems

5. CPU

This configuration is similar to OS configuration. Using CPU can more accurately limit the user's installation environment:

"cpu" ["x64", "AMD64"] // Applicable cpu
"cpu" ["!arm", "!mips"] // disabled cpu

As you can see, the difference between the blacklist and the whitelist is that the blacklist has a "!" in front.

6. License

license field is used to specify the open source agreement of the software. The open source agreement describes the rights that others have after obtaining the code, what operations can be performed on the code, and what operations are prohibited.

Common protocols are as follows:

• MIT: As long as users include the copyright notice and license notice in their copies of the project, they can do whatever they want with your code and you don't have to take any responsibility.
• Apache: Similar to MIT, but also includes terms for contributors to provide patent licenses to users.
• GPL: Users who modify the project code must publish their modifications when redistributing the source code or binary code.
  

The field can be declared like this:

"license": "MIT"

7. Third-party configuration

The package.json file can also carry command-specific configurations, such as Babel , ESLint , etc. Each of them has unique properties, such as eslintConfig , babel , etc. They are command specific and how to use them can be found in the corresponding command/project documentation. Let's take a look at several commonly used third-party configuration items.

1. typings

The typings field is used to specify the TypeScript entry file:

"typings": "types/index.d.ts",

The function of this field is the same as that main configuration.

2. eslintConfig

The configuration of eslint can be written in a separate configuration file .eslintrc.json , or in the eslintConfig configuration item of the package.json file.

"eslintConfig": {
      "root": true,
      "env": {
        "node": true
      },
      "extends": [
        "plugin:vue/essential",
        "eslint:recommended"
      ],
      "rules": {},
      "parserOptions": {
        "parser": "babel-eslint"
     },
}

3. babel

Babel is used to specify the compilation configuration of Babel. The code is as follows:

"babel": {
 "presets": ["@babel/preset-env"],
 "plugins": [...]
}

4. unpkg

Use this field to enable the CDN service for all files on npm . The CND service is provided by unpkg:

"unpkg": "dist/vue.js"

5. lint-staged

lint-staged is a tool that runs linters on Git staging files. After configuration, a lint check can be performed on all files each time a file is modified. It is usually used in conjunction with gitHooks .

"lint-staged": {
 "*.js": [
   "eslint --fix",
    "git add"
  ]
}

When using lint-staged , each code submission will only check the currently modified files.

6. gitHooks

gitHooks is used to define a hook to perform ESlint checks before committing. After executing the lint command, the files in the temporary storage area will be automatically repaired. The repaired files will not be stored in the staging area, so you need to use the git add command to add the repaired files back to the staging area. After executing the pre-commit command, if there are no errors, the git commit command will be executed:

"gitHooks": {
 "pre-commit": "lint-staged"
}

Here is to cooperate with the above lint-staged to check the code.

7. browserslist

browserslist field is used to tell which browsers and versions are supported. It is used by Babel , Autoprefixer , and other tools to add the required polyfill and fallback to target browsers. For example, the value of this field in the example above is:

"browserslist": {
  "production": [
    ">0.2%",
    "not dead",
    "not op_mini all"
  ],
  "development": [
    "last 1 chrome version",
    "last 1 firefox version",
    "last 1 safari version"
  ]
}

An object is specified here that defines the browser requirements for production and development environments. development above specifies the last version of chrome , Firefox , and safari browsers that are supported in the development environment. This property is a configuration tool for sharing target browsers and node versions between different front-end tools. It is used by many front-end tools, such as Babel and Autoprefixer .

This is the end of this article about the front-end JavaScript butler package.json. For more relevant front-end butler package.json content, please search for previous articles on 123WORDPRESS.COM or continue to browse the following related articles. I hope everyone will support 123WORDPRESS.COM in the future!