NPM Package.json Properties in a detailed

Chapter Catalogue

• Overview
• Name
• Version
• Description
• Keywords
• Homepage
• Bugs
• License
• User-related properties: Author, contributors
• Files
• Main
• Bin
• Mans
• Directories
• Directories.lib
• Directories.bin
• Directories.man
• Directories.doc
• Directories.example
• Repository
• Scripts
• Config
• Dependencies
• URLs as Dependencies
• Git URLs as Dependencies
• GitHub URLs
• Local Paths
• Devdependencies
• Peerdependencies
• Bundleddependencies
• Optionaldependencies
• Engines
• Enginestrict
• Os
• Cpu
• Preferglobal
• Private
• Publishconfig
• DEFAULT VALUES
• Reference Document List (https://docs.npmjs.com/)

Overview

This document is your own view of the official document Understanding + translation, content is the Package.json configuration inside the meaning of the attribute. Package.json must be a strict JSON file, not just an object inside JS. Many of these properties can be generated by npm-config.

Name

The most important attribute in Package.json is the name and version two properties, which must be required, otherwise the module cannot be installed, together these two properties form a unique identifier for the NPM module. The module version should also change as the content changes in the module.
The Name property is your module, and here are some naming conventions:

• Name must be less than or equal to 214 bytes, including the prefix name (such as Xxx/xxxmodule).
• Name cannot be "_" or "." Beginning
• Cannot contain uppercase letters
• Name becomes part of the URL and cannot contain URL illegal characters
  Here are some suggestions for 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" fi Eld. (see below.)
• The Name property becomes a module URL, a parameter on the command line, or a folder name, and any non-URL-safe characters cannot be used in name or with "_" or "." Beginning
• The name attribute may be written in the parameters of require (), so it's best to take a short, semantically-typed value.
• Before creating a module, you can go to the back of the URL to check if name is already occupied. https://www.npmjs.com/

The Name property can have some prefixes such as e.g. @myorg/mypackage. In the documentation for Npm-scope (7), you can see the detailed description

Version

Version must be parsed by a node-semver module that NPM relies on. See the dependencies module below for specific rules

Description

A description, convenient for others to understand the role of your module, search time also useful.

Keywords

An array of strings to make it easier for others to search this module

Homepage

Project home Page URL
Note: This project home page URL and URL properties are different, if you fill out the URL attribute, the NPM registration tool will think that you publish the project to another place, the acquisition module will not be obtained from the NPM official repository, but will redirect to the URL property configured address.
(The word Spit (spit) is used in the original document, and the author says he is not joking:)

Bugs

Fill in a bug submission address or a mailbox, the person who is trapped by your module can spit through the trough here, for example:

{ "url" : "https://github.com/owner/project/issues", "email" : "[email protected]"}

URLs and email can be filled or not, if only one, can be directly written as a string instead of the object. This URL is used if the URL,NPM bugs command is filled in.

License

You should develop a protocol for your module that will let users know what permissions they have to use your module, and what restrictions are available for using that module. The simplest, such as your use of Bsd-3-clause or MIT protocols, are as follows:
{"License": "Bsd-3-clause"}
You can check the protocol list at the https://spdx.org/licenses/address.

User-related properties: Author, contributors

"Author" is a yard farm, "contributors" is an array of yards. "Person" is an object that has some description attributes, like this:

{ "name" : "Barney Rubble", "email" : "[email protected]", "url" : "http://barnyrubble.tumblr.com/"}

It can also be abbreviated in the following format, and NPM will help convert:
"Barney rubble [email protected] (http://barnyrubble.tumblr.com/)"
The email and URL properties can be omitted in fact. There is also a "maintainers" (maintainer) attribute that describes the user information.

Files

The value of the "Files" property is an array, the content is the file name or folder name under the module, if it is a folder name, all the files under the folder will also be included (unless the file is excluded by some other configuration)
You can also create a ". Npmignore" file under the module root directory (Windows cannot be created directly under "." Starting with a file that was created using the Linux command-line tool like Git bash, the file written in this file will be excluded even if it is written in the Files property, which is similar to the ". Gitignore" file.

Main

The main property specifies the primary entry file for the program. This means that if your module is named Foo and the user installs the module and uses require ("foo") to use the module, the require returned is the object that Module.exports points to in the file specified by the main property.
It should point to a file in the root directory of the module. For large logarithmic modules, this attribute is more of a main entry file for the module, but many modules do not write this property.

Bin

Many modules have one or more executable modules that need to be configured under Path paths, and NPM makes this work very simple (in fact NPM itself is installed as an executable command via the Bin property)
If you want to use this feature of NPM, configure a bin property inside Package.json. The Bin property is a command named Key, and the local file name is named value map as follows:

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

When the module is installed, if it is installed globally, NPM will create a soft connection in the bin directory for the files configured in the bin (for Windows systems, by default in the C:\USERS\USERNAME\APPDATA\ROAMING\NPM directory), if installed locally, A soft link is created under the./node_modules/.bin/directory within the project.
So, as in the above example, when you install MyApp, NPM creates a soft link for cli.js on the/usr/local/bin/myapp path.
If your module has only one executable file, and its command name and module name are the same, you can write a single string instead of the configuration above, for example:

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

The function is the same as the following:

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

Mans

Set up one or more files with an array to get the man command under Linux to find the document address.
If only one file is specified, the 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 man foo command will get the contents of the./man/doc.1 file.
If the man file name does not start with the module name, the module name prefix is added to the 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" ]}

Some files are created as a result of the man Foo and man Foo-bar commands.
The man file must end with a number or, if it is compressed, end with. Gz. The number indicates which part of the man the file will be installed in.

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

The Man foo and Man 2 foo two commands are created.

Directories

Commonjs through the directories to develop a number of methods to describe the structure of the module, see npm Package.json file Https://registry.npmjs.org/npm/latest, you can find the contents of this field inside.

At present, this configuration has no effect, in the future may be a number of tricks to complete.

Directories.lib

Tell the user where the Lib directory is in the module, this configuration does not currently have any effect, but is a useful information for the person who uses the module.

Directories.bin

If you specify the bin directory here, this configuration file will be added to the bin path, if you have already configured the bin directory in Package.json, then the configuration here will not play any role.

Directories.man

Specifies a directory in which the man file is a syntax sugar that configures the man file.

Directories.doc

Put some markdown files in this directory, and maybe one day they will be shown friendly (it should be on NPM's website)

Directories.example

Put some sample scripts, maybe one day will be useful--!

Repository

Specify a code store address that is useful 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 in a repository on GitHub, GitHub Gist, BitBucket, or Gitlab, NPM install can be done using an abbreviated tag:

"repository": "npm/npm""repository": "gist:11081aaa281""repository": "bitbucket:example/repo""repository": "gitlab:another/repo"

Scripts

The Scripts property is an object that specifies the commands that need to be executed for each aspect of the project's life cycle. Key is the event in the life cycle, and value is the command to execute.
The specific content has the install start stop and so on, see https://docs.npmjs.com/misc/scripts

Config

Used to set up project configurations that do not change a few items, such as port.
Users can use the following usage:

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

Config can be modified via NPM config set Foo:port 80来. See Https://docs.npmjs.com/misc/config

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

Dependencies

The Dependencies property is an object that configures a module-dependent list of modules, key is the module name, value is a version range, the version range is a character, and can be split by one or more spaces.
Dependencies can also be specified as a git address or a compressed package address.
Do not write the test tool or transpilers into the dependencies. Here are some of the wording, see Https://docs.npmjs.com/misc/semver

• Version exact match
• >version must be greater than one version
• >=version greater than or equal to
• <version less than
• <=versionversion less than
• ~version "Approximately equals", specific rules see semver documentation
• ^version "compatible version" specific rules see semver documentation
• 1.2.x only 1.2-point version
• http://... See the following URL as a description of denpendencies
• • Any version
• "" NULL character, and * same
• Version1-version2 equivalent to >=version1 <=version2.
• Range1 | | Range2 range 1 and Range 2 meet any one of the lines
• Git... See git URL below as a description of denpendencies
• User/repo See the following GitHub warehouse instructions
• Tag released by a special tab, see Npm-tag documentation Https://docs.npmjs.com/getting-started/using-tags
• Path/path/path See the description of the local module below
  Here are some of the possible formulations:

{ "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 "," "" "": " 2.x", "thr": "3.3.x", "lat": "latest", "dyl": " File:". /dyl "}}                   

URLs as Dependencies

In the version range can write a URL point to a compressed package, the module will be installed to download the package to install the module locally.

Git URLs as Dependencies

The Git URL can look like the following:

git://github.com/user/project.git#commit-ishgit+ssh://[email protected]:project.git#commit-ishgit+ssh://[email protected]/project.git#commit-ishgit+http://[email protected]/project/blah.git#commit-ishgit+https://[email protected]/project/blah.git#commit-ish

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

GitHub URLs

Support for GitHub's username/modulename, #后边可以加后缀写明分支hash或标签:

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

Local Paths

npm2.0.0 version above can provide a local path to install a local module, installed through NPM install XXX--save, the format is as follows:

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

The relative paths generated by Package.json are as follows:

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

This attribute is useful when developing offline or testing for NPM install, and does not want to make a NPM server on its own, but it should not be used when releasing the module to a public repository.

Devdependencies

If someone wants to download and use your module, they may not want or need to download some additional testing or documentation frameworks that you use during the development process.
In this case, the best approach is to add these dependencies to the object of the Devdependencies property.
These modules will be installed on NPM link or npm install, and can be managed like any other NPM configuration, as described in the NPM config documentation.
for some cross-platform build tasks, such as compiling coffeescript into JavaScript, You can do this by configuring the Prepublish script inside the script property of Package.json, and then the Coffee-script module that needs to be relied on is written in the Devdependencies attribute species.
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 runs before it is published, so the user does not have to go through the process of compiling itself before using it. In development mode, running NPM install also executes this script (see NPM Script document), so it can be easily debugged.

Peerdependencies

Sometimes do plug-in development, such as grunt tools such as plug-ins, they are often developed on the basis of a version of Grunt, and in their code will not appear require ("grunt") such a dependency, The dependencies configuration also does not write grunt dependencies, in order to show that this module can only be used as a plug-in run in the host version of the range, you can configure the peerdependencies:

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

The above configuration ensures that when NPM installs, Tea-latte will be installed with the 2.x version of tea, and that their two dependencies are similar:
├── [email protected]
└── [email protected]
The purpose of this configuration is to let NPM know that if you want to use this plug-in module, be sure to install a compatible version of the host module.

Bundleddependencies

The above words are less d, written bundledependencies can also.
Specifies the modules that will be packaged together when publishing.

Optionaldependencies

If a dependent module can be used and you want NPM to continue running when the module is not found or unreachable, you can put this module dependency into the Optionaldependencies configuration. This configuration is written in the same way as the dependencies, the difference is that the module installation failure will not cause NPM install failure.
Of course, this module requires you to handle the actual 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 overrides the configuration in the dependencies, preferably in one place.

Engines

You can specify the node version range for 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 can.
You can also specify a number of NPM versions to properly install your module, for example:
{"Engines": {"NPM": "~1.0.20"}}
Note that unless you set the Engine-strict property, the engines property is for informational purposes only.

Enginestrict

Note: This property has been deprecated and will be eliminated in NPM version 3.0.0.

Os

You can specify which operating system your module can run on:
"OS": ["Darwin", "Linux"]
You can also specify a blacklist instead of a whitelist:
"OS": ["!win32"]
The operating system of the service is judged by Process.platform, which allows the black-and-white list to exist at the same time, although there is no need to do so ...

Cpu

Restricted modules can only be run under certain CPU architectures
"CPU": ["x64", "IA32"]
You can also set a blacklist:
"CPU": ["!arm", "!mips"]
CPU architecture judged by Process.arch

Preferglobal

If your package is primarily used for installation to a global command-line application, the value is set to True and provides a warning if it is installed locally. In fact, this configuration does not prevent the user from installing the module locally, only to prevent the module from being incorrectly used to cause some problems.

Private

If this property is set to TRUE,NPM will refuse to publish it, which is to prevent a private module from being inadvertently published. If you just want the module to be published to a specific NPM repository, such as an internal repository, you can configure the warehouse parameters with the publishconfig below.

Publishconfig

This configuration is a collection of some values that will be used when the module is published. If you don't want the module to be flagged as up-to-date by default or published to the public repository by default, you can configure the tag or warehouse address here.

DEFAULT VALUES

NPM has set some default parameters, such as:
"Scripts": {"Start": "Node Server.js"}
If there is a Server.js file under the module root directory, NPM start will run the file by default.
"Scripts": {"Preinstall": "Node-gyp Rebuild"}
If Binding.gyp is in the module root directory, NPM will default to compiling preinstall scripts with Node-gyp
"Contributors": [...]
If there is a authors file in the root directory of the module, NPM will parse the data for each row in the name (URL) format to add to the contributors, you can add the line comment by #

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)

NPM Package.json Properties in a detailed