Description

The package.json file must be a JSON formatted file and not a JavaScript Object.

Most of the points that will be covered in this section are related to the configuration settings described in config.

name

If you are publishing a package, name and version are the most important and essential fields. name and version must be able to be combined into a completely unique identifier. If the package generates an update, then the version field must also be updated to generate a new unique name-version identifier. If you do not intend to publish your package, then the name and version fields are optional.

name is the name of the package. It is referred to as the package name.

Some rules.

  • Package names must be less than or equal to 214 characters in length. Include the scope of scoped packages.
  • The package name of scoped packages can start with a dot or an underscore. This rule does not apply to unscoped packages (non-scoped packages).
  • Names are not allowed to contain uppercase letters.
  • A package name can be treated as part of a URL, a parameter on the command line, or the name of a folder. Therefore, package names are not allowed to contain non-URL-safe characters.

Some suggestions.

  • Do not use the name of a node core module as a package name.
  • Do not include “js” or “node” in the name. Packages will default to js because you are writing a package.json file, use the “engines” field if you need to specify an engine. (mentioned below)
  • The package name is passed as an argument to the require() function, so the name should be as short as possible, but needs to ensure some semantics.
  • Before naming a package, you may want to check if the npm repository already contains a package with the same name. https://www.npmjs.com/

The name can optionally be preceded by a scope, e.g. @myorg/mypackage. Click scope for more details.

version

If you are publishing a package, name and version are the most important and essential fields. name and version must be able to be combined into a completely unique identifier. If the package generates an update, then the version field must also be updated to generate a new unique name-version identifier. If you do not intend to release your package, then the name and version fields are optional.

The Version value must be parsable by node-semver.

description

The description of the package, a string that will help people find your package and can be displayed in the npm search list.

keywords

Package related keywords, an array of strings to help people find your package, which can be displayed in the npm search list.

homepage

The package’s homepage url.

For example.

1

"homepage": "https://github.com/owner/project#readme"

bugs

The url address of the issue tracking page for the package, or an email address where bug messages can be sent. Users who use this package can send you issue details if they encounter a bug or other problem.

It should look like this.

1
2
3
4

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

You can specify at least one of the url or email fields. If you only want to provide an url, you can specify the value of bugs as a normal string instead of an object.

If an url is provided, it will be used by the npm bugs command.

license

You can specify a license for your package to let others know if there are license restrictions on using the package.

If a regular license is specified, such as BSD-2-Clause or MIT, the current SPDX license identifier needs to be added to the license being used.

1

{ "license" : "BSD-3-Clause" }

You can check the SPDX License IDS Complete List. Normally you should select the license recognized by OSI.

If multiple licenses are included, you can use SPDX License Expression Syntax v2.0, like the following.

1

{ "license" : "(ISC OR GPL-3.0)" }

If you are using a license that is not in the scope of SPDX, or if you are using a custom license, then you can specify it like the following.

1

{ "license" : "SEE LICENSE IN <filename>" }

Then include the <filename> file under the root path of the package.

Some older packages specify the license using objects or the licenses attribute that contains an array of licensed objects.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

// Not valid metadata
{ "license" :
    { 
        "type" : "ISC",
        "url" : "https://opensource.org/licenses/ISC"
    }
}

// Not valid metadata
{ "licenses" :
    [
        {
            "type": "MIT",
            "url": "https://www.opensource.org/licenses/mit-license.php"
        },
        {
            "type": "Apache-2.0",
            "url": "https://opensource.org/licenses/apache2.0.php"
        }
    ]
}

These styles are currently discarded. Use SPDX expressions instead.

1
2

{ "license": "ISC" }
{ "license": "(MIT OR Apache-2.0)" }

Finally, if you do not want to grant others the right to use private or unpublished packages under any terms. You can specify this:

1

{ "license": "UNLICENSED" }

Also consider setting "private": true to prevent accidental publication.

Person fields: author, contributors

author is a person and contributors is an array of persons. A person is an object containing the name attribute and optionally the url and email attributes, like this.

1
2
3
4
5

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

Or you can use the following string shorthand and npm will parse the following string for you.

1

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

emial and url are optional fields.

npm will set a top-level maintainers field with your npm user information.

funding

You can specify an object containing a URL that provides up-to-date information about funding your package development, either as a string URL or as an array.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

"funding": {
    "type" : "individual",
    "url" : "http://example.com/donate"
}

"funding": {
    "type" : "patreon",
    "url" : "https://www.patreon.com/my-account"
}

"funding": "http://example.com/donate"

"funding": [
    {
        "type" : "individual",
        "url" : "http://example.com/donate"
    },
    "http://example.com/donateAlso",
    {
        "type" : "patreon",
        "url" : "https://www.patreon.com/my-account"
    }
]

Users can use the npm fund command to list the funding url for all the project’s dependent packages, or they can use npm fund <projectname> to list the funding url for a given package (when there are multiple URLS, the first one will be accessed).

files

The optional files field is a file-matching string, and when your package is installed as a project dependency, the files specified by the files field will be included. File matching uses a syntax similar to that of the .gitignore file. Ignoring this field is equivalent to ["*"], which means that all files are included.

Some special files will be included or excluded, whether they are specified by the files field or not (see below).

You can also provide a .npmignore file in the package root or subdirectory, similar to .gitignore, which will prevent files from being included. If .npmignore is in the root of the package, it will not overwrite the contents of the files field, but if .npmignore is in a subdirectory, it will overwrite the contents of the files field. If there is a .gitignore file but no .npmignore file, then the contents of the .gitignore file will be used as the contents of .npmignore by default.

The files specified by the files field cannot be excluded by .npmignore or .gitignore.

Some files will always be included in packages, no matter how they are set.

  • package.json
  • README
  • CHANGES / CHANGELOG / HISTORY
  • LICENSE / LICENCE
  • NOTICE
  • The file specified by the “main” field

README , CHANGES , LICENSE & NOTICE can be any file extensions.

Some files will always be excluded from the package, no matter how it is set.

  • .git
  • CVS
  • .svn
  • .hg
  • .lock-wscript
  • .wafpickle-N
  • .DS_Store
  • npm-debug.log
  • .npmrc
  • node_modules
  • config.gypi
  • package-lock.json
  • All files containing the * character (not compatible with Windows)

main

The main field is a module ID that is just the entry point for your program. If your package is named foo and the user installs your package and imports your package using require("foo"), then the object exported from the file specified in the main field of your application’s package.json file will be returned.

It should be a module ID relative to the root path of the package.

For most modules, it makes the most sense to have a main script and not much else.

browser

If your package is intended to be used in a client application, then the browser field should be specified instead of the main field. This can hint to the user that it may depend on something basic that is not available in the nodejs environment (like window).

1

"browser": "./lib/browser/main.js"

bin

Many packages have one or more executables that they want to install in the PATH. npm makes this easy (in fact, it is the npm executable that is installed using this feature).

To use this feature, you need to specify the bin field in the package.json file, which represents the mapping of commands to local file names. When doing a global install, npm symbolically links this file to prefix/bin (symlink), and when doing a local install, it symbolically links this file to node_modules/.bin/.

For example, package.json for myapp contains the following.

1

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

When you install myapp globally, npm will create a symbolic link from the cli.js script to the usr/local/bin/myapp directory.

If you only have one executable, then you can provide a string like this.

1
2
3
4
5

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

The above is written in a way that is equivalent to

1
2
3
4
5

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

Finally, make sure that the contents of the file referenced by the bin field starts with #! /usr/bin/env node to indicate that node is required for the script to execute.

directories

The package documentation structure is described by this field and is rarely used.

  1. directories.lib
  2. directories.bin
  3. directories.man
  4. directories.doc
  5. directories.example
  6. directories.test

repository

Tells you where the package repository is located. If the git repository is on Github, using the npm docs command will redirect you to the repository page.

1
2
3
4
5
6
7
8
9

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

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

If it’s a Github, Github gist Bitbucker or GitLab repository, you can use the abbreviated form.

1
2
3
4
5
6
7
8
9

"repository": "npm/npm"

"repository": "github:user/repo"

"repository": "gist:11081aaa281"

"repository": "bitbucket:user/repo"

"repository": "gitlab:user/repo"

If the package.json file is not in the project’s root directory, you can specify the directory where the package is located.

1
2
3
4
5

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

scripts

The scripts property is a dictionary containing script commands that run at different times during the package’s lifecycle.

More detailed information is available on the scripts page.

config

The config object can be used to configure the parameters of scripts, for example.

1
2
3
4

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

There is a start command and the port can be referenced via the npm_package_config_port variable. Users can also override the configuration via npm config set foo:port 8001.

More information can be found at config and scripts.

dependencies

Specifies project dependencies, the value is the package name plus the version number.

The version number can specify a range, and has the following syntax.

  • version : the exact version, e.g. 1.0.0
  • >version : greater than version
  • >=version : greater than or equal to
  • <version : less than
  • <=version : less than or equal to
  • ~version : allows patch-level changes, e.g. ~1.2.3 means >=1.2.3 <1.3.0
  • ^version : allows changes that do not change the leftmost non-zero version number, e.g. ^1.2.3 means >=1.2.3 <2.0.0
  • 1.2.x
  • http://...
  • *
  • version1 - version2 is the same as >=version1 <=version2

You can get more information about version at semver.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{ 
    "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 can be used instead of version numbers.

You can also use the local path.

1
2
3
4
5
6

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

devDependencies

Dependency packages for the development environment.

peerDependencies

Field to prevent packages from being installed repeatedly.

For example, suppose your application depends on packages A, B and C, and B and C depend on A. When you install A, B and C, B and C will install A repeatedly, so you can add A to C under the peerDependencies field, so that when your application installs dependencies, A will only be installed once, and B and C will not install A repeatedly.

This is generally used to specify the host version that the current package is compatible with. For example, if we want to write a webpack plugin that is currently compatible with webpack 3.x, we can specify it as follows.

1
2
3
4
5

{
    "peerDependencies": {
        "webpack": "3.x"
    }
}

bundledDependencies

The bundled dependencies will be packaged together with the package specified by this object in the final package to be released.

optionalDependencies

Optional dependencies, use this field to specify optional packages if you want the project to work even if the installation fails, or if you want npm to keep running.

engines

You can specify some runtime environments, such as node and npm.

1
2
3
4
5
6

{ 
    "engines" : {
        "node" : ">=0.10.3 <0.12",
        "npm" : "~1.0.20"
    }
}

Reference