Getting started with package.json configuration interpretation

foreword

package.json is a json file that every front-end project will have, located in the root directory of the project. Many scaffolds will automatically initialize package.json for us when creating a project. There are many configurations in package.json that are closely related to the project. Understanding them is helpful for the development of the project. Next, let's start to understand the configuration of package.json.

Today we mainly introduce some commonly used configurations, which are divided into seven categories, namely:

• describe configuration
• script placement
• file configuration
• Dependency configuration
• publish configuration
• System Configuration
• third party configuration

1. Describe the configuration

Mainly the basic information of the project, including name, version, description, warehouse, author, etc.

name

The name of the project, if it is a third-party package, it can be installed through npm install by this name.

npm install name

version

The version number of the project, the version number of the open source project follows the semver semantic specification, as follows:

Briefly introduce what this array represents:

• 1 represents the major version number Major, which is usually updated when major function updates are involved;
• 2 represents the minor version number Minor, and this version number will be updated when new features are introduced but no destructive changes are made and it is still backward compatible;
• 3 represents the revision number Patch, and this version number will be updated when some problems are fixed and no destructive changes are produced;

Going back to the version field of package.json, name + version can together form a completely unique project identifier, so they are the two most important fields.

repository

The warehouse address and version control information of the project.

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

description

The description of the project will be displayed on the npm official website, so that others can understand the project faster.

"description": "package.json配置解读"

keywords

The technical keywords of the project. Appropriate keywords can better retrieve the project on the npm official website.

"keywords": [
  "component",
  "components",
  "design",
  "framework",
  "frontend",
  "ui",
  "axios"
 ],

license

The project's open source license. The copyright owner of the project can use the open source license to restrict the use, copying, modification and redistribution of the source code. Common open source licenses include BSD, MIT, Apache, etc. For details, please refer to this article by Mr. Ruan Yifeng on how to choose an open source license .

"license": "BSD"

author

Needless to say, this field refers to the author of the project.

"author": "May",

2. File configuration

Including the files and entry information included in the project.

files

When the project is released, you can specify the content that needs to be released together through files to control the size of the npm package to avoid too long installation time. The files specified in the package.json, license, README and main fields will be included by default when publishing. Files such as node_modules, lockfile, etc. are ignored.
On this basis, we can specify other content that can be published, which can be individual files, file files, and files matched by wildcards. Under normal circumstances, the built product and type file will be specified in files, and the files in the src directory do not need to be followed by the release.

"files": [
  "file.js",
  "may/",
  "global/*.{js,json}"
 ]

type

After node supports ES modules, ES modules are required to use the .mjs suffix file name. As long as a file ending in .mjs is encountered, it is considered an ES module. If you do not want to modify the file extension, you can modify the type value to module in package.json.

"type": "module"

If you still want to use the CommonJs module specification, you need to end the file of the CommonJS module with .cjs, but it is recommended not to mix these two modules, otherwise an error will be reported.

main

When the project is released, the files specified in the package.json, license, README and main fields will be included by default, because the main field specifies the entry file of the project, which can be used in both browser and Node environments.
If the main field is not set, then the entry file is index.js in the root directory.

browser

The entry file specified in the main field can be used in both browser and Node environments. If you only want to use it on the web side and not allowed to use it on the server side, you can specify the entry through the browser field.

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

module

The module field can be used to specify the entry file of the ES module.

"module": "./index.mjs"

When a project defines main, browser and module at the same time, construction tools such as webpack and rollup will perceive these fields and search for different entry files according to the environment and different module specifications.
For example, when webpack builds a project, the default target is 'web', which means Web build. Its resolve.mainFeilds field defaults to ['browser', 'module', 'main'].

module.exports = {
    
    
  //...
  resolve: {
    
    
    mainFields: ['browser', 'module', 'main'],
  },
};

At this point, the entry file will be searched in the order of browser -> module -> main.

exports

Node supports defining the exports field in package.json in 14.13, and has the function of conditional export. The exports field can configure module entry files corresponding to different environments, and when it exists, it has the highest priority. For example, use the require and import fields to define the entry respectively according to the module specification:

"exports": {
    
    
  "require": "./index.js",
  "import": "./index.mjs"
 }
}

Such a configuration will import files from different entries when using import 'xxx' and require('xxx'), and exports also supports using browser and node fields to define entries in browser and Node environments. The above writing method is actually equivalent to:

"exports": {
    
    
  ".": {
    
    
    "require": "./index.js",
    "import": "./index.mjs"
  }
 }
}

Why add a level and put require and import under "."?
Because exports not only support the default export of the configuration package, but also support the subpath of the configuration package.

workspaces

The workspace configuration of the project is used to manage multiple sub-projects under the local root directory. The package under workspaces can be automatically soft-linked to node_modules in the root directory during npm install, without manually performing npm link operations.
The workspaces field receives an array, which can be folder names or wildcards. for example:

"workspaces": [
  "workspace-s"
]

Indicates that there is another project under the workspace-s directory, which also has its own package.json.

package.json
workspace-a
  └── package.json

Usually sub-projects will be managed flatly in the packages directory, so the workspaces in the root directory are usually configured as:

"workspaces": [
  "packages/*"
]

3. Script configuration

scripts

Some built-in script commands of the specified project, these commands can be executed by npm run. It usually includes CI commands such as project development and construction, such as:

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

We can use the command npm run build to execute the project build.
In addition to specifying the basic command, you can also cooperate with pre and post to complete the pre- and subsequent operations of the command, such as:

"scripts": {
    
    
  "build": "webpack",
  "prebuild": "xxx", // build 执行之前的钩子
  "postbuild": "xxx" // build 执行之后的钩子
}

When the npm run build command is executed, the above commands will be executed in the order of prebuild -> build -> postbuild.
But such implicit logic is likely to cause confusion in the execution workflow, so both pnpm and yarn2 have abandoned this pre/post automatic execution logic.
If you need to open it manually, the pnpm project can be set

enable-pre-post-scripts=true

config

config is used to set the parameters of the scripts in scripts at runtime. For example, set the port to 3001:

"config": {
    
    
  "port": "8080"
}

When executing the script, we can access 3001 through the npm_package_config_port variable.

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

Four. Conclusion

Today we briefly learned about the basic configuration of package.json. Writing an article will introduce other configurations about package.json. With this knowledge, we can better understand the project. But the content in package.json is much more than that, we need to study further.