package.json is one JSON
object. The first table lists every field in npm’s documentation (npm 11), in its
order; the later sections cover version ranges, lifecycle scripts and the fields that
Node.js and other tools read.
Sources: npm 11’s package.json and scripts pages; the node-semver README for range expansions; Node.js’s Modules: Packages; the Corepack README; TypeScript’s Publishing handbook page.
npm fields
| Field | Type | Meaning |
|---|---|---|
name | string | Package name; required to publish. At most 214 characters including a scope (@scope/name); new names lower case and URL-safe; an unscoped name may not start with . or _. |
version | string | Semantic version that node-semver can parse; required to publish. Name and version together identify a release. |
description | string | Short summary, shown by npm search. |
keywords | array of strings | Search terms. |
homepage | string | Project home page URL. |
bugs | object or string | Issue tracker: { "url", "email" }; a string is the URL. |
license | string | SPDX identifier or expression, SEE LICENSE IN <file>, or UNLICENSED. The old object form and licenses array are deprecated. |
author | person | { "name", "email", "url" }, or one string Name <email> (url). |
contributors | array of persons | Other people, in the same forms. (npm sets maintainers itself.) |
funding | object, string or array | Where to fund the project: { "type", "url" } or a URL; shown by npm fund. |
files | array of patterns | What goes into the published tarball (default: everything). Always included: package.json, README, LICENSE or LICENCE, the main file and bin files. Always left out: version-control and editor files, node_modules, .npmrc, npm-debug.log, lock files. .npmignore and .gitignore also apply. |
exports | object or string | Entry points, with conditions (see Node.js fields). Only listed paths can be imported. |
main | string | Main module; default index.js. |
type | string | How Node.js treats .js files: "module" (ES modules) or "commonjs" (default). npm ignores it. |
browser | string | Entry point for browser bundles. |
bin | object or string | Command names mapped to files, linked onto the PATH on install; a string uses the package name as the command. Files start #!/usr/bin/env node. |
man | string or array | Man page files, names ending in a section number (optionally .gz). |
directories | object | bin: every file in the folder is a command (not with bin); man: every page in the folder. |
repository | object or string | { "type": "git", "url", "directory" }; shorthands user/repo, github:, gist:, bitbucket:, gitlab: are normalised on publish. |
scripts | object | Script names mapped to shell commands; see scripts. |
gypfile | boolean | false stops npm building a binding.gyp native add-on automatically. |
config | object | Values given to scripts as npm_package_config_<key> environment variables. |
dependencies | object | Names mapped to version specs; needed at run time. |
devDependencies | object | Needed only for development; installed only in the root project. |
peerDependencies | object | Host packages this one works with; installed automatically since npm 7. |
peerDependenciesMeta | object | Per peer: { "optional": true } stops it being installed automatically. |
bundleDependencies | array or boolean | Dependencies packed inside the tarball; true means all. bundledDependencies is accepted too. |
optionalDependencies | object | Like dependencies, but installation goes on if one fails. Overrides an entry of the same name in dependencies. |
overrides | object | Forces versions of packages deep in the tree; root project only. Values are specs, $name (the version of a direct dependency) or replacements; keys can nest by parent and carry a version, e.g. "foo@1". |
engines | object | Ranges of node and npm needed; advisory unless engine-strict is set. |
os | array of strings | Supported process.platform values; !name excludes one. |
cpu | array of strings | Supported process.arch values; !name excludes one. |
libc | string | libc the package needs, e.g. glibc; applies only when os is linux. |
devEngines | object | What developers of the package need: cpu, os, libc, runtime, packageManager, each { "name", "version", "onFail" } (or an array of them) with onFail warn, error (default) or ignore. Checked before install, ci and run. |
private | boolean | true: npm refuses to publish it. |
publishConfig | object | Settings used when publishing, such as registry, tag, access. |
workspaces | array of strings | Folders or globs of workspace packages, linked into the root node_modules. |
Defaults npm fills in: a start script of node server.js
when that file exists; an install script of node-gyp rebuild
when binding.gyp exists and there is no install or
preinstall; contributors from an AUTHORS file.
Version specs
| Form | Example | Matches |
|---|---|---|
| Exact | 1.2.3 | Only that version. |
| Comparison | >1.2.3, >=, <, <= | The bound. |
| Tilde | ~1.2.3, ~1.2, ~1 | >=1.2.3 <1.3.0-0; >=1.2.0 <1.3.0-0; >=1.0.0 <2.0.0-0. |
| Caret | ^1.2.3, ^0.2.3, ^0.0.3 | >=1.2.3 <2.0.0-0; >=0.2.3 <0.3.0-0; >=0.0.3 <0.0.4-0. |
| X-range | 1.2.x, 1.x, *, "" | >=1.2.0 <1.3.0-0; >=1.0.0 <2.0.0-0; >=0.0.0 (by default not pre-releases); the empty string is the same as *. |
| Hyphen range | 1.2.3 - 2.3.4 | >=1.2.3 <=2.3.4. |
| Union | 1.2.7 || >=1.2.9 <2.0.0 | Matches if every comparator of at least one ||-separated set matches. |
| Dist-tag | latest, next | The version that tag points to. |
| Tarball URL | https://…/pkg.tgz | That tarball. |
| Git URL | git+https://…/repo.git#v1.0.0 | Protocols git, git+ssh, git+http, git+https, git+file; #commit-ish or #semver:<range>. |
| GitHub shorthand | user/repo#branch | A GitHub repository. |
| Local path | file:../lib | A folder; ../, ~/, ./ and / become file:. |
| Alias | npm:other@^1.0.0 | Another package installed under this name. |
Scripts
Any name can be run with npm run <name>, and a script named
pre<name> or post<name> runs before or after it.
npm runs these by itself:
| Command | Scripts run, in order |
|---|---|
npm install, npm ci | preinstall, install, postinstall, prepublish, preprepare, prepare, postprepare |
npm rebuild | preinstall, install, postinstall, then prepare only if the folder is a symbolic link |
npm cache add, npm diff | prepare |
npm pack | prepack, prepare, postpack |
npm publish | prepublishOnly, prepack, prepare, postpack, publish, postpublish |
npm test | pretest, test, posttest |
npm start | prestart, start, poststart |
npm stop | prestop, stop, poststop |
npm restart | prerestart, restart, postrestart; with no restart script, stop then start |
npm version | preversion, version, postversion |
After node_modules changes (not in global mode) | dependencies |
prepublish is deprecated and does not run on publish. prepack
also runs when a Git dependency is installed.
Node.js and other tools
| Field | Read by | Meaning |
|---|---|---|
name, main | Node.js | Used for self-reference imports; the default module when there is no exports. |
exports | Node.js | Entry points; when present, only these can be loaded. Subpath keys may use *, a plain string replacement ("./features/*.js": "./src/features/*.js"), and a null target excludes a subpath. Values may be objects of conditions, earlier keys winning: "node-addons", "node", "import", "require" (never both with import), "module-sync", "default" (always last). Community conditions, ignored unless enabled with --conditions: "types" (first), "browser", "development", "production". |
imports | Node.js | Imports for the package’s own modules; keys must start with #, and targets may be external packages. |
type | Node.js | "module": .js files are ES modules; "commonjs" or absent: CommonJS. .mjs and .cjs are always ES module and CommonJS. |
packageManager | Corepack | name@version with name yarn, npm or pnpm, optionally +<algorithm>.<hash>, e.g. "yarn@3.2.3+sha224.953c…". |
types (synonym typings) | TypeScript | The main declaration file, e.g. "./lib/main.d.ts". |
typesVersions | TypeScript | Semver ranges of TypeScript mapped to path redirects, read first and in order; falls back to types. |