Detailed explanation of npm package.json properties

This article is reproduced from https://www.cnblogs.com/tzyy/p/5193811.html, author: TZYY

Overview

package.json must be a strict json file, not just an object in js.Many of these properties can be generated through npm-config

name

The most important properties in package.json are the two properties name and version. These two properties are required, otherwise the module cannot be installed. These two properties together form the unique identifier of an npm module.When the content in the module changes, the module version should also change together. The name attribute is your module name. Here are some naming rules:

• name must be less than or equal to 214 bytes, including the prefix name (such as xxx/xxxmodule).

• name cannot start with "_" or "."

• Cannot contain capital letters

• name will become part of the url and cannot contain illegal url characters.

  Here are some suggestions from the official website documentation:

• Do not use the same name as the node core module

• Do not include "js" and "node" in name.It's assumed that it's js, since you're writing a package.json file, and you can specify the engine using the "engines" field. (See below.)

• The name attribute will become a parameter in the module url, the command line, or a folder name. Any non-url safe characters cannot be used in name, nor can it start with "_" or "."

• The name attribute may be written in the require() parameter, so it is best to have a short and semantic value.

• Before creating a module, you can go to the following URL to check whether name is already occupied. https://www.npmjs.com/

  • # 发布一个包的时候，需要检验某个包名是否存在
    npm search <ModuleName>

The name attribute can have some prefixes such as e.g. @myorg/mypackage. Detailed description can be seen in the documentation of npm-scope(7)

version

version must be resolvable by a node-semver module that npm depends on.See the dependencies module below for specific rules.

description

A description helps others understand the function of your module, and is also useful when searching.

keywords

A string array to facilitate others to search for this module

homepage

Project homepage url Note: The homepage URL of this project is different from the url attribute. If you fill in the url attribute, the npm registration tool will think that you have published the project elsewhere. When obtaining the module, it will not be obtained from the npm official warehouse, but will be redirected to the address configured with the url attribute. (The word spit was used in the original document, and the author said he was not joking:)

bugs

Fill in a bug submission address or email. People who have been tricked by your module can complain here, for example:

{
    "url" : "https://github.com/owner/project/issues",
    "email" : "project@hostname.com"
}

URL and email can be filled in or left out. If you only fill in one, you can write it directly as a string instead of an object.If the url is filled in, the npm bugs command will use this url.

license

You should create a protocol for your module that lets users know what permissions they have to use your module, and what restrictions there are on using the module.The simplest one, for example if you use a protocol such as BSD-3-Clause or MIT, is as follows:

{ "license" : "MIT" }

you can https://spdx.org/licenses/ Check the protocol list for this address.

User-related attributes: author, contributors

author is a coder, contributors is an array of coders.person is an object with some descriptive properties, like this:

{
    "name" : "Barney Rubble",
    "email" : "b@rubble.com",
    "url" : "http://barnyrubble.tumblr.com/"
}

You can also abbreviate it in the following format, and npm will help convert it:

"Barney Rubble b@rubble.com (http://barnyrubble.tumblr.com/)"

The email and url attributes can actually be omitted.There is also a maintainers attribute describing user information.

files

The value of the files attribute is an array, and the content is the file name or folder name under the module. If it is a folder name, all files under the folder will also be included (unless the file is excluded by other configurations) You can also create a .npmignore file in the module root directory (files starting with "." cannot be created directly under Windows, use Linux command line tools such as git bash to create them). Files written in this file will be excluded even if they are written in the files attribute. The writing of this file is similar to ".gitignore".

main

The main attribute specifies the main entry file of the program.This means that if your module is named foo, and the user installs this module and uses this module through require("foo"), then the content returned by require is the object pointed to by module.exports in the file specified by the main attribute. It should point to a file in the module's root directory.For the large logarithm module, this attribute is more about letting the module have a main entry file. However, many modules do not write this attribute.

bin

Many modules have one or more executable modules that need to be configured in the PATH path. npm makes this task very simple (in fact, npm itself is also installed as an executable command through the bin attribute) If you want to use this function of npm, configure a bin attribute in package.json.The bin attribute is a map whose command name is key and the local file name is value, as follows:

{
    "bin" : { "myapp" : "./cli.js" }
}

When installing the module, if it is installed globally, npm will create a soft link in the bin directory for the file configured in bin (for Windows systems, it will be in the C:\Users\username\AppData\Roaming\npm directory by default). If it is installed locally, a soft link will be created in the ./node_modules/.bin/ directory within the project. Therefore, according to the above example, when you install myapp, npm will create a soft link for cli.js in the /usr/local/bin/myapp path. If your module has only one executable file and its command name is the same as the module name, you can just write a string instead of the above configuration, for example:

{ 
    "name": "my-program",
    "version": "1.2.5", 
    "bin": "./path/to/program"
}

The effect is the same as the following writing:

{ 
    "name": "my-program", 
    "version": "1.2.5", 
    "bin" : { 
        "my-program" : "./path/to/program" 
    }
}

man

Specify one or specify some files through an array to let the man command under Linux find the document address. If only one file is specified, man+module name is used directly after installation, regardless of the actual name of the file specified by man.For example:

{
    "name" : "foo",
    "version" : "1.2.3", 
    "description" : "A packaged foo fooer for fooing foos", 
    "main" : "foo.js", 
    "man" : "./man/doc.1"
}

The contents of the ./man/doc.1 file will be obtained through the man foo command. If the man file name does not start with the module name, the module name will be prefixed during installation.Therefore, the following configuration:

{ 
    "name" : "foo", 
    "version" : "1.2.3", 
    "description" : "A packaged foo fooer for fooing foos", 
    "main" : "foo.js", 
    "man" : [ "./man/foo.1", "./man/bar.1" ]
}

Several files are created as a result of the man foo and man foo-bar commands. man files must end with a number or, if compressed, .gz.The number indicates which part of man the file will be installed into.

{ 
    "name" : "foo", 
    "version" : "1.2.3",
    "description" : "A packaged foo fooer for fooing foos", 
    "main" : "foo.js", 
    "man" : [ "./man/foo.1", "./man/foo.2" ]
}

Two commands, man foo and man 2 foo, will be created.

directories

CommonJs uses directories to develop some methods to describe the structure of modules. Take a look at npm's package.json file. https://registry.npmjs.org/npm/latest , you can find the content of this field inside. Currently this configuration has no effect, and some tricks may be devised in the future.

directories.lib

Tell the user where the lib directory in the module is. This configuration currently has no effect, but it is a very useful information for people who use the module.

directories.bin

If you specify the bin directory here, the files under this configuration will be added to the bin path. If you have configured the bin directory in package.json, the configuration here will have no effect.

directories.man

Specify a directory, which contains man files. This is a syntax sugar for configuring man files.

directories.doc

Put some markdown files in this directory, maybe one day they will be displayed in a friendly way (should be on the npm website)

directories.example

Putting up some sample scripts, maybe they will be useful someday - -!

repository

Specifying a code storage location is helpful for people who want to contribute code to your project.Like this:

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

"repository" :
  { 
      "type" : "svn", 
      "url" : "https://v8.googlecode.com/svn/trunk/"
  }

If your module is placed in a GitHub, GitHub gist, Bitbucket, or GitLab repository, you can use the abbreviation tag when npm install:

"repository": "npm/npm"

"repository": "gist:11081aaa281"

"repository": "bitbucket:example/repo"

"repository": "gitlab:another/repo"

scripts

The scripts attribute is an object that specifies the commands that need to be executed in each link of the project's life cycle.The key is the event in the life cycle, and the value is the command to be executed. The specific content includes install start stop, etc. For details, see https://docs.npmjs.com/misc/scripts

config

Used to set some project configurations that do not change much, such as ports, etc. Users can use the following usage:

http.createServer(...).listen(process.env.npm_package_config_port)

The config can be modified via npm config set foo:port 80.For details, see https://docs.npmjs.com/misc/config

{ 
    "name" : "foo", 
    "config" : { "port" : "8080" }
}

dependencies

The dependencies attribute is an object that configures a list of modules that the module depends on. The key is the module name, and the value is the version range. The version range is a character and can be separated by one or more spaces. Dependencies can also be specified as a git address or a compressed package address. Don't write test tools or transpilers into dependencies.Here are some writing methods, see https://docs.npmjs.com/misc/semver for details

• version exact match version
• >version must be greater than a certain version
• >=version greater than or equal to
• <version is less than
• <=versionversion is less than
• ~version "approximately equal to", please see the semver documentation for specific rules.
• ^version "Compatible version" specific rules can be found in the semver document.
• 1.2.x only version 1.2.x
• http://... See below for description of url as dependencies
• • any version
• "" null character, same as *
• version1 - version2 is equivalent to >=version1 <=version2.
• range1 || range2 Any one of range 1 and range 2 is fine.
• git... See the description of git url as denpendencies below
• user/repo See See the description of the GitHub repository below
• tag is a special tag published, see npm-tag documentation https://docs.npmjs.com/getting-started/using-tags
• path/path/path See description of local modules below The following writing methods are possible:

{ "dependencies" :
  { "foo" : "1.0.0 - 2.9999.9999"
  , "bar" : ">=1.0.2 <2.1.2"
  , "baz" : ">1.0.2 <=2.3.4"
  , "boo" : "2.0.1"
  , "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0"
  , "asd" : "http://asdf.com/asdf.tar.gz"
  , "til" : "~1.2"
  , "elf" : "~1.2.3"
  , "two" : "2.x"
  , "thr" : "3.3.x"
  , "lat" : "latest"
  , "dyl" : "file:../dyl"
  }
}

URLs as Dependencies

In the version range, you can write a URL pointing to a compressed package. When the module is installed, the compressed package will be downloaded and installed locally in the module.

Git URLs as Dependencies

The Git url can look like this:

git://github.com/user/project.git#commit-ish
git+ssh://user@hostname:project.git#commit-ish
git+ssh://user@hostname/project.git#commit-ish
git+http://user@hostname/project/blah.git#commit-ish
git+https://user@hostname/project/blah.git#commit-ish

commit-ish can be any tag, hash, or branch that can be checked out. The default is the master branch.

GitHub URLs

Supports Github's username/modulename writing method. You can add a suffix after # to indicate the branch hash or label:

{
  "name": "foo",
  "version": "0.0.0",
  "dependencies": {
    "express": "visionmedia/express",
    "mocha": "visionmedia/mocha#4727d357ea"
  }
}

Local Paths

npm version 2.0.0 or above can provide a local path to install a local module, which can be installed through npm install xxx --save. The format is as follows:

../foo/bar
~/foo/bar
./foo/bar
/foo/bar

The relative path generated by package.json is as follows:

{
  "name": "baz",
  "dependencies": {
    "bar": "file:../foo/bar"
  }
}

This attribute is useful when you need to use npm install for offline development or testing and do not want to build an npm server yourself. However, this attribute should not be used when publishing modules to public repositories.

devDependencies

If someone wants to download and use your module, they may not want or need to download some of the additional testing or documentation framework you use during development. In this case, the best approach is to add these dependencies to the object in the devDependencies property. These modules will be installed when npm link or npm install, and can also be managed like other npm configurations. See npm's config document for details. For some cross-platform build tasks, such as compiling CoffeeScript into JavaScript, you can complete this task by configuring the prepublish script in the script attribute of package.json, and then the coffee-script module that needs to be relied upon is written in the devDependencies attribute. For example:

{ "name": "ethopia-waza",
  "description": "a delightfully fruity coffee varietal",
  "version": "1.2.3",
  "devDependencies": {
    "coffee-script": "~1.6.3"
  },
  "scripts": {
    "prepublish": "coffee -o lib/ -c src/waza.coffee"
  },
  "main": "lib/waza.js"
}

The prepublish script will be run before publishing, so users no longer have to complete the compilation process before using it.In development mode, running npm install will also execute this script (see npm script documentation), so it can be easily debugged.

peerDependencies

Sometimes we do some plug-in development, such as plug-ins for grunt and other tools. They are often developed on the basis of a certain version of grunt. However, dependencies such as require("grunt") do not appear in their code, and dependencies on grunt are not written in the dependencies configuration. In order to illustrate that this module can only run as a plug-in in a certain version range of the host, you can configure peerDependencies:

{
  "name": "tea-latte",
  "version": "1.3.5",
  "peerDependencies": {
    "tea": "2.x"
  }
}

The above configuration ensures that tea-latte will be installed together with the 2.x version of tea during npm install, and their dependencies are at the same level: ├── tea-latte@1.3.5 └── tea@2.2.0 The purpose of this configuration is to let npm know that if you want to use this plug-in module, please ensure that a compatible version of the host module is installed.

bundledDependencies

The above word is missing a d, so it can be written as bundleDependencies. Specify the modules that will be packaged together when released.

optionalDependencies

If a dependent 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. The difference is that failure to install the module written here will not cause npm install to fail. Of course, this kind of module requires you to handle the exact situation of the module in your code, for example:

try {
  var foo = require('foo')
  var fooVersion = require('foo/package.json').version
} catch (er) {
  foo = null
}
if ( notGoodFooVersion(fooVersion) ) {
  foo = null
}

// .. then later in your program ..

if (foo) {
  foo.doFooThings()
}

The configuration in optionalDependencies will override the configuration in dependencies. It is best to write it in only one place.

engines

You can specify the node version range in which the project runs, as follows: { "engines" : { "node" : ">=0.10.3 <0.12" } } Like dependencies, if you don't specify a version range or specify *, any version of node will work. You can also specify some npm version to install your module correctly, for example: { "engines" : { "npm" : "~1.0.20" } } Note that unless you set the engine-strict attribute, the engines attribute is for reference only.

engineStrict

Note: This attribute has been deprecated and will be removed in npm 3.0.0.

os

You can specify which operating systems your module can only run on: "os" : [ "darwin", "linux" ] It is also possible to specify a blacklist instead of a whitelist: "os" : [ "!win32" ] The operating system of the service is determined by process.platform. This attribute allows black and white lists to exist at the same time, although there is no need to do so...

cpu

Restrict the module to only run under a certain CPU architecture "cpu" : [ "x64", "ia32" ] You can also set up a blacklist: "cpu" : [ "!arm", "!mips" ] The cpu architecture is determined by process.arch

preferGlobal

Set this value to true if your package is intended primarily for command-line applications installed globally, and provide a warning if it is installed locally.In fact, this configuration does not prevent users from installing the module locally, but only prevents the module from being used incorrectly and causing some problems.

private

If this property is set to true, npm will refuse to publish it. This is to prevent a private module from being published accidentally.If you only want the module to be published to a specific npm repository, such as an internal repository, configure the repository parameters in publishConfig below.

publishConfig

This configuration is a collection of values that will be used when the module is released.If you don't want the module to be marked as latest by default, or to be published to a public repository by default, you can configure the tag or repository address here.

DEFAULT VALUES

npm sets some default parameters, such as: "scripts": {"start": "node server.js"} If there is a server.js file in the module root directory, npm start will run this file by default. "scripts":{"preinstall": "node-gyp rebuild"} If there is binding.gyp in the module root directory, npm will use node-gyp by default to compile the preinstall script. "contributors": [...] If there is an AUTHORS file in the module root directory, npm will parse the data of each line in Name (url) format and add it to contributors. You can add line comments with #

Reference document list (https://docs.npmjs.com/)

semver(7) npm-init(1) npm-version(1) npm-config(1) npm-config(7) npm-help(1) npm-faq(7) npm-install(1) npm-publish(1) npm-rm(1)