An in-depth analysis of the package.json file

Understand package.json

Under the root directory of each project (package downloaded from npm, or other nodejs projects), there is generally a package.json file, which defines the various modules required for the project, as well as the project configuration information (Metadata such as name, version, license, how to start the project, run scripts, etc.). The npm install command automatically downloads the required modules based on this configuration file.

The package.json file is a JSON object, and each member of the object is a setting of the current project. For example, name is the project name, version is the version (following the format of "major version.minor version.minor version"). It will also play multiple roles in the project life cycle, including development, testing, and online versions.

package.json functions

• as a description file that describes the packages your project depends on.
• It allows us to use "semantic versioning rules" (described later) to indicate the version of your project's dependent packages
• so that your build can better communicate with other developers. Share for easy reuse

How to create package.json

1. Use the command line tool client CLI

npm init

This will start the command line questionnaire, which will create package.json in the directory where you started the command.

Front-end (vue) entry to mastery course: Enter learning

2. Create default value

To get the default value package.json , please run npm init with --yes or -y flag:

npm init -y

This method will use package.json from the current one. The information extracted from the directory generates default values, skipping the step of answering questions.

3. Manually create

a new package.json file directly in the project root directory, and then enter the relevant content. Please see the notes on package.json below for details.

Detailed explanation of common fields in package.json files

1. Name

is a required field, which is the name of the current modulepackage. The length must be less than or equal to 214 characters. It cannot start with "." (dot) or "_" (underscore) and cannot contain uppercase letters.

This name may be passed as a parameter to require(), so it should be short, but still meaningful.

2. Version

is a required field, the version number of the current package, the default is 1.0.0 when created for the first time.

version must be resolvable by a node-semver module that npm depends on. Defines the version iteration progress of the current project. (Follow the format of "major version. minor version. minor version")

Maybe many friends now don't pay attention to or don't care about the version number, and prefer to use the version number of the product, or the git hashcode method.

3. The description

optional field must be a string. The description information of the current package is a string. It helps people find the package when using npm search.

If there is no description information in package.json, npm uses the first line of README.md in the project as the description information. This description information will help others search for your project, so it is recommended to write description information well.

4. The main

optional field specifies the entry file for project loading.

The default value of this field is index.js under the module root directory.

5. The scripts

optional field. scripts is a hash object composed of script commands. They are executed in different life cycles of the package. The key is the life cycle event and the value is the command to be run. Specifies the npm command line abbreviation for running the script command. For example, start specifies the command to be executed when running npm run start. We can customize the command we want to run the script.

Reference: http://www.ruanyifeng.com/blog/2016/10/npm_scripts.html

scripts configuration execution script

• 1) Execute the command echo xxx

• 2. to execute the file under node_modules/.bin.

Why can it be executed?

When I execute npm run, a new Shell will be automatically created and the specified script command will be executed in this Shell. Therefore, as long as the command can be run by Shell (usually Bash), it can be written in the npm script. will also copy node_modules/.bin in the current directory to the path of the current system (it is only a temporary copy. After the execution is completed, the PATH variable will be restored to its original state), so all scripts in the node_modules/.bin subdirectory of the current directory, All can be called directly using the script name without adding a path.

For example:

if we use node to execute a node.js service, node + 文件can use node server.js ; we can also use webpack to package the front-end file, webpack-dev-server . Of course, webpack and webpack-dev-server need to be installed. Dependent modules;

"scripts": {   
    "build": "webpack --mode=development",
    "dev": "webpack-dev-server --mode=development --contentBase=./dist",
    "server":"node app.js"
  }

We enter npm run server in the command line tool, and node app.js will be called to help us run it.

Short form:

npm start is npm run start
npm stop is the abbreviation of npm run stop npm test is the abbreviation of npm run test npm restart is the abbreviation of npm run stop && npm run restart && npm run start

Commonly used scripts ----- Online collection transfer

// Delete directory "clean": "rimraf dist/*",

// Build an HTTP service "serve" locally: "http-server -p 9090 dist/",

//Open the browser "open:dev": "opener http://localhost:9090",

//Refresh "livereload" in real time: "live-reload --port 9091 dist/",

// Build HTML file "build:html": "jade index.jade > dist/index.html",

// As long as the CSS file changes, re-execute the build "watch:css": "watch 'npm run build:css' assets/styles/",

// As long as the HTML file changes, re-execute the build "watch:html": "watch 'npm run build:html' assets/html",

//Deploy to Amazon S3
"deploy:prod": "s3-cli sync ./dist/ s3://example-com/prod-site/",

//Build favicon
"build:favicon": "node scripts/favicon.js",

"start": "cross-env NODE_ENV=production node server/index.js",

6. dependencies and devDependencies

are optional fields. The dependencies field specifies the modules that the project depends on, and devDependencies specifies the modules required for project development.

The value points to an object. Each member of this object consists of the module name and the corresponding version requirement, indicating the dependent module and its version range.

There is no package.json created by default, it will be generated when we install npm install a module.

npm install express
npm install express --save
npm install express --save-dev

The above code means to install the express module separately.

• When there are no parameters behind it, it means to install it into dependencies attribute.
The --save parameter means to write the module into the dependencies attribute.
• --save-dev means to write the module
• --save dependencies attribute.
• Enter the devDependencies attribute.

7. bundledDependencies

optional field, other dependencies packaged at the same time when publishing the package.

8. peerDependencies

optional field, compatibility dependency, if your project or module depends on another module at the same time, but the version it depends on is different.

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.

{
  "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 chai version must be 1.x If the dependency specified by your project is version 2.0 of chai , an error will be reported.

9. Bin

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

Create the /bin/www file in the project root directory

Configure

"bin"

/usr/bin/env node

  "lee-cli":"./bin/www"
}

npm link adds the value path of the bin attribute in the package to a global link, creates a shortcut connection, and

executes lee-cli on the command line to execute the bin/www file. The process is:

In the above example, www will create a symbolic link node_modules/.bin/www . Since the node_modules/.bin/ directory will be added to the system's PATH variable at runtime, these scripts can be called directly through commands without a path when running npm.

10. config

The config field is used to output values ​​to environment variables

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

If we want to change it, we can use

npm config set package:port 80

11. The engines

optional field specifies the platform version on which the module runs, such as a certain version of Node or a browser. You can also specify the applicable npm version.

"engines" : { 
"node" : 
">=0.10.3 <0.12"
}

12. License

optional field, indicating the definition of the license applicable to the code described in package.json. Different protocols have different restrictions. Let users know what permissions they have to use your module and what restrictions there are on using it.

Please refer to: choosealicense.com/ to choose a license.

For example: MIT: maximum permission, others can change your code after downloading it, default installation value.

13. Author

optional field, project developer.

14. Private

optional field, Boolean value, whether private. When set to true, npm refuses to publish.

This is a way to prevent private packages from being released to outsiders. If you wish to wrap a package to be published only to a specific registry (e.g., an internal registry), you can use the publishConfig dictionary description below to override the registry configuration parameters at publish-time.

15. The keywords

optional field, project keywords, is a string array. It helps people find the package when using npm search.

16. The os

optional field specifies the operating system on which the module can run.

17. style

style specifies the location of the style file when used by the browser.

18.

The type of place where the repository package code is stored can be git or svn. git can be on Github.

19. The homepage

optional field does not have URLs with protocol prefixes such as http://.

Version problem:

version: "1.0.0"

1.0.0:

The first digit change means: incompatibility with old code, large-scale update, new version release;

the second digit means: some functions have been added, backward compatibility;

the third digit

means: some functions have been added, backward compatibility

bit means: small patches, bug corrections;

when we publish the project, we use npm + git

• to use npm version patch (patch patch). This will change the third digit of the version; use git tag to execute and it will automatically be in git
• Use npm version minor to change the second digit of the version number; synchronize the git version;
• use
• npm version major to change the first digit of the version number; synchronize the git version;

npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]

major: major version number minor: minor version number patch: patch number premajor: preliminary major version prepatch: preliminary minor version prerelease: pre-release version

ps: Note, if an error is reported: Git working directory not clean, it means that you need git status to be clean now of.

git add .
git commit -m "package.json detailed explanation"

npm versin monir -m"增加版本号"

git push -u origin master

How to formulate rules?

As users, we can indicate in the package.json file how much updates we can accept for this package (assuming that we are currently relying on version 1.2.4):

• If we only intend to accept updates to the patch version (that is, the last digit change ), you can write it like this:

  1.2
   1.2.x
   ~1.2.4

• If you accept minor version updates (changes in the second position), you can write like this:

  1
  1.x
  ^1.2.4

• If you can accept major version updates (naturally accept minor version and patch version changes), you can write like this:

  *x

  To summarize: there are three types of version changes, which type of update of dependent packages is accepted? Write the version number accurately to the previous digit.

Version cycle and stages:

• α-Alpha The first phase is generally only for internal testing
• β-Beta The second phase has eliminated most of the imperfections in the software, but there may still be defects and loopholes, and is generally provided to specific To test and use it in the user group;
• γ-RC is the third stage. At this time, the product is quite mature and only needs to be further optimized in some places before it can be released on the market.

For example:

2.1.0-beta.1 is generally used by users like this This kind of thing will not be installed. This kind can be used by the inside and testers.

~

Differentiate between installing Dependencies and dependencies ?

devDependencies are modules required for development, so we can install them as needed during the development process to improve our development efficiency, such as some well-known third-party libraries, webpack , rollUp , less , babel , etc. There is no need to install it in the production environment.

The following libraries are recommended to be installed into devDependencies :

• unit test support (mocha, chai);
• syntax compatibility (babel);
• syntax conversion (jsx to js, ​​coffeescript to js, ​​typescript to js)
• program construction and optimization (webpack, gulp, grunt, uglifyJS);
• css processor (postCSS, SCSS, Stylus);
• code specification (eslint);

dependency package (specify, update, local, use, uninstall)

1. Install local dependency package

npm install jquery

This command will create a in the current directory node_modules directory, and then download the package we specified into this directory.

2. To specify the installation version, you can @版本号after the package name.

If the name of a package starts with package @ , it is a scoped package .

npm install [email protected]
npm install jquery@">=1.1.0 <2.2.0"

npm install jquery@latest

is updated, the version number in dependencies will also change.

3. Update the dependent package

npm update jquery

4. Use the package

let jquery = require('jquery');

<script src="/node_modules/jquery/dist/jquery.js">//This needs to pay attention to the path</script>

6 , Uninstall the dependent package

npm uninstall jquery

Semantic versioning (semantic versioning rules)

• https://docs.npmjs.com/about-semantic-versioning

• https://github.com/npm/node-semver

package.json Notes

according to the above When we use npm init we will be asked to fill in several items. Some of them are optional and some are required. These required fields are all fields that a package.json content must have: name and version . If not, install cannot be executed.

• name: all lowercase, no spaces, use hyphens and underscores in sequence
• version: version number, follow the semantic versioning rules mentioned above xxx

Other notes:

• adding Chinese comments will cause compilation errors