The package.json property you didn’t know about

An overview of the

Package. json must be a strict JSON file, not just an object in JS. Many of these attributes can be generated using nPm-config

name

The most important properties in package.json are the name and version attributes, which are required otherwise the module cannot be installed. Together, these two attributes form the unique identifier of an NPM module. When the contents of a module change, the module version should change as well. The name attribute is the name of your module. Here are some naming conventions:

• The name must contain a maximum of 214 bytes, including the prefix (for example, XXX/xxxModule).

• Name cannot start with “_” or “.”

• Cannot contain capital letters

• The name will be part of the URL and cannot contain invalid URL characters

  Here are some suggestions from the official 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 becomes the module URL, a parameter on the command line, or a folder name. Any non-URL-safe character cannot be used in name and cannot start with “_” or “.

• The name attribute may be written as an argument to require(), so it is best to take a short, semantic value.

• Before creating a module, you can check the following url to see if the name is already used. www.npmjs.com/

  • When publishing a package, you need to check if a package name exists
    npm search <ModuleName>
    Copy the code

The name attribute can have prefixes such as e.g. @myorg/mypackage. You can see the details in the nPM-Scope (7) documentation

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, easy to understand your module function, also useful when searching.

keywords

An array of strings to facilitate others to search this module

homepage

Note: The project home URL is different from the URL property. If you fill in the URL property, the NPM registration tool will assume that you have published the project elsewhere. It will not fetch the module from the NPM repository, but will redirect it to the url property configured address. (the original document uses the word “spit”, but the author says he’s not kidding 🙂

bugs

Fill in a bug submission address or email address for people to be teased by your module, such as:

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

Url and email can be filled in arbitrarily or not. If only one is filled in, it can be written as a string instead of an object. If you fill in the URL, the NPM Bugs command uses that URL.

license

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

{ "license" : "MIT" }
Copy the code

You can check out the list of protocols at spdx.org/licenses/.

Properties that relate to users: Author, Polymorphism

The author is a coding molecule, and that molecule is an array of coding molecules. Person is an object with some description attributes, like this:

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

NPM will help with the conversion:

"Barney Rubble [email protected] (http://barnyrubble.tumblr.com/)"
Copy the code

The email and URL attributes can actually be omitted. A maintainers property also describes the user information.

files

The value of the files property is an array of module file names or folder names. If it is a folder name, You can also create a. Npmignore file in the root directory of the module. (On Windows you can’t create a file that starts with a “.”, use a Linux command line tool such as Git bash.) Files written in this file are excluded even if they are written in the files property. This file is written like “.gitignore”.

main

The main property specifies the main entry file for the program. This means that if your module is named foo and the user installs the module and uses it via require(“foo”), then require returns the same object that module.exports points to in the file specified by the main property. It should point to a file in the module root directory. For large log modules, this property is more about having a main entry file for the module, whereas many modules do not write this property.

bin

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

{
    "bin" : { "myapp" : "./cli.js"}}Copy the code

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

{ 
    "name": "my-program"."version": "1.2.5"."bin": "./path/to/program"
}
Copy the code

The effect is the same as the following:

{ 
    "name": "my-program"."version": "1.2.5"."bin" : { 
        "my-program" : "./path/to/program"}}Copy the code

man

Make a file or an array of files for the man command on Linux to find document addresses. If only one file is specified, use the man+ module name after installation, regardless of the actual name of the file specified by man. Such as:

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

The man foo command yields the contents of the./man/doc.1 file. If the man file name does not start with the module name, the installation will be prefixed with the module name. 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"]}Copy the code

Files are created as a result of the man foo and man foo-bar commands. The man file must end with a number, or.gz if compressed. The numbers indicate 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"]}Copy the code

The commands man foo and man 2 foo are created.

directories

CommonJs through directories to formulate some method to describe the structure of the module, see NPM package. Registry.npmjs.org/npm/latest json file.

directories.lib

This configuration tells the user where the lib directory is in the module. It doesn’t do anything right now, but it’s a useful piece of information for anyone who uses the module.

directories.bin

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

directories.man

Specify a directory filled with man files. This is a syntax sugar for configuring man files.

directories.doc

Put some Markdown files in this directory and they may eventually be presented in a friendly way (presumably on NPM’s website).

directories.example

Put out some sample scripts that might come in handy one day.

repository

Specifying a code 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/"
  }
Copy the code

If your module is in a GitHub, GitHub gist, Bitbucket, or GitLab repository, NPM install can be done with the abbreviation flag:

"repository": "npm/npm"

"repository": "gist:11081aaa281"

"repository": "bitbucket:example/repo"

"repository": "gitlab:another/repo"
Copy the code

scripts

The scripts property is an object that specifies the commands that need to be executed during each phase of the project lifecycle. Key is the life cycle event, and value is the command to execute. Specific content such as install start stop, see https://docs.npmjs.com/misc/scripts

config

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

http.createServer(...) .listen(process.env.npm_package_config_port)Copy the code

Config can be modified by NPM config set foo:port 80. See docs.npmjs.com/misc/config

{ 
    "name" : "foo"."config" : { "port" : "8080"}}Copy the code

dependencies

The Dependencies property is a list of modules that a module depends on. The key is the module name, and the value is the version range. The version range is a character separated by one or more Spaces. Dependencies can also be specified as a Git address or a zip package address. Do not write test tools or transpilers into Dependencies. Here are some wording, see docs.npmjs.com/misc/semver

• Version Indicates the exact match version
• >version Must be greater than a certain version
• >= Version must be greater than or equal to
• The < version is less than
• < = versionversion less than
• ~version “approximately equal to”, see the Semver documentation for details
• ^version “Compatible version” for details, see the Semver documentation
• 1.2.x is only available in version 1.2
• http://… See the URL below for a description of Denpendencies
• • Any version
• “” empty character, same as *
• Version1-version2 Equivalent to >=version1 <=version2.
• Range1 | | range2 range 1 and 2 to meet any one will do
• git… See git URL as Denpendencies below for a description
• User /repo See the GitHub repository description below
• Tag publishes a special tag, see nPM-tag documentation docs.npmjs.com/getting-sta…
• Path /path/path see the following local module description:

{ "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"}}Copy the code

URLs as Dependencies

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

Git URLs as Dependencies

Git urls 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
Copy the code

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

GitHub URLs

Github username/modulename is supported. # can be suffix to indicate branch hash or tag:

{
  "name": "foo"."version": "0.0.0"."dependencies": {
    "express": "visionmedia/express"."mocha": "visionmedia/mocha#4727d357ea"}}Copy the code

Local Paths

NPM 2.0.0 or higher provides a local path to install a local module, using NPM install XXX –save to install it in the following format:

../foo/bar
~/foo/bar
./foo/bar
/foo/bar
Copy the code

Package. json generates relative paths as follows:

{
  "name": "baz"."dependencies": {
    "bar": "file:.. /foo/bar"}}Copy the code

This property is useful for offline development or testing where NPM install is required and you don’t want to build your own NPM server, but should not be used when publishing modules to a public repository.

devDependencies

If someone wants to download and use your modules, they probably don’t want or need to download some of the extra tests or documentation frameworks you use during development. In this case, the best approach is to add these dependencies to the object of the devDependencies property. These modules are installed by NPM Link or NPM Install and can be managed like any other NPM configuration, as described in the NPM Config documentation. For cross-platform build tasks, such as compiling CoffeeScript to JavaScript, you can do this by configuring the prepublish script in the script property of package.json, The coffee-script module that you need to depend on is written in the devDependencies property. Such as:

{ "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"
}
Copy the code

The prePublish script runs before publication, so users don’t have to compile it themselves before using it. Running NPM Install in development mode also executes this script (see the NPM Script documentation), making it easy to debug.

peerDependencies

Grunt (grunt, grunt, grunt, grunt, grunt, grunt, grunt) To show that this module can only run as a plug-in in a certain version range of the host, configure peerDependencies:

{
  "name": "tea-latte"."version": "1.3.5"."peerDependencies": {
    "tea": "2.x"}}Copy the code

This configuration ensures that tea latte is installed with the 2.x version of tea when NPM is installed, and that the dependency between the two is the same: ├─ [email protected] ├─ [email protected] The purpose of this configuration is to let NPM know that if you want to use this plug-in module, make sure that a compatible version of the host module is installed.

bundledDependencies

“BundleDependencies”. Specifies the modules that will be packaged together for release.

optionalDependencies

If a dependency module is available and you want NPM to continue running if the module is not found or retrieved, you can put the module dependency in the optionalDependencies configuration. NPM install < span style = “box-sizing: border-box; color: RGB (51, 51, 51); line-height: 22px; font-size: 14px! Important; white-space: inherit! Important;” Of course, such modules need to be handled in your own code, such as:

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()
}
Copy the code

The configuration in optionalDependencies overrides the configuration in Dependencies and is best written in one place only.

engines

You can specify the node version range in which your project runs as follows: {“engines” : {“node” : “>=0.10.3 <0.12″}} As in dependencies, if you do not specify the node version range or specify *, any node version will work. You can also specify some version of NPM that will install your modules correctly, for example: {” Engines “: {” NPM” : “~1.0.20”}} Note that unless you set engine-strict, the Engines property is for reference only.

engineStrict

Note: This property is deprecated and will be deprecated in NPM 3.0.0.

os

You can specify which operating system your modules should only run on: “OS” : [” Darwin “, “Linux”] You can also specify a blacklist rather than a whitelist: “OS” : The operating system of the [“! Win32 “] service is determined by process.platform, and this property allows blacklists to exist simultaneously, although there is no need to do so…

cpu

“CPU” : [” X64 “, “ia32”] You can also set the blacklist: “CPU” : [“! Arm “, “! MIPS “] The CPU architecture can be determined by process.arch

preferGlobal

This value is set to true if your package is primarily used to install to global command-line applications, providing a warning if it is installed locally. In fact, this configuration does not prevent users from installing modules locally, but only prevents the module from being used incorrectly and causing problems.

private

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

publishConfig

This configuration is a collection of values that will be used when the module is published. If you don’t want the module to be marked as up to date by default, or 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’s binding.gyp in the module root directory, NPM will default to use Node-gyp to compile preinstall’s script” 3 “: […]. If there is an AUTHORS file in the module root, NPM pars each row of data in the Name (URL) format to add into the molecule, which can be annotated with #.

Reference Document List

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)