package.json Explained: Every Field That Matters
The manifest of a Node project. Learn the fields that affect resolution, the scripts, the exports map, and the version ranges.
By Velloreth
The manifest
package.json is the manifest of a Node project. It names the project, declares its dependencies, defines its scripts, and controls how the package is resolved by a consumer.
{
"name": "my-app",
"version": "1.0.0",
"type": "module",
"main": "./dist/index.js",
"exports": {
".": "./dist/index.js",
"./utils": "./dist/utils.js"
},
"scripts": {
"build": "tsc",
"test": "vitest"
},
"dependencies": {
"express": "^4.19.2"
},
"devDependencies": {
"typescript": "^5.4.0"
}
}
Identity fields
name is the package name. It must be lowercase, and it is the name used to install the package.
version is the semantic version. It is required for a published package and optional for a private application.
private: true prevents an accidental publish. It is worth setting on an application.
description, keywords, author, license are metadata. The license field matters for a published package, and a missing one is a legal ambiguity.
engines declares the Node version the package supports.
{
"engines": {
"node": ">=20"
}
}
packageManager tells Corepack which manager and version to use, which keeps a team consistent.
{
"packageManager": "pnpm@9.0.0"
}
Dependencies
dependencies are needed at runtime. They are installed in production.
devDependencies are needed to develop, test or build. They are skipped in a production install.
peerDependencies are provided by the consumer. A plugin declares the framework it works with as a peer, so the consumer’s version is used rather than a second copy.
{
"peerDependencies": {
"react": ">=18"
}
}
optionalDependencies are installed if possible, and a failure does not fail the install. A native module with a platform-specific build is the usual case.
The rule: a package that is imported by the application’s runtime code is a dependency. A package used only by a script, a test or a build step is a devDependency.
Version ranges
| Range | Allows |
|---|---|
1.2.3 | exactly 1.2.3 |
~1.2.3 | 1.2.x, a patch update |
^1.2.3 | 1.x.x, a minor or patch update |
>=1.2.3 | any version at or above |
* | any version |
1.2.x | 1.2.x |
The caret is the default when a package is added with npm install. It allows a minor update, which is a compatible change by the semantic versioning contract.
The lockfile pins the actual version. The range in package.json is the constraint, and the lockfile is the resolution. A build uses the lockfile.
A range that is too loose is a risk. A * allows a major update, which can break the build. A caret is the common balance.
Scripts
{
"scripts": {
"dev": "vite",
"build": "tsc && vite build",
"test": "vitest run",
"lint": "eslint .",
"prepublishOnly": "npm run build"
}
}
A script is a shell command. It runs with node_modules/.bin on the path, so a local binary is available by name.
pre and post hooks run automatically.
{
"scripts": {
"prebuild": "rimraf dist",
"build": "tsc",
"postbuild": "node scripts/copy-assets.js"
}
}
npm run build runs prebuild, then build, then postbuild. The hooks are convenient and they are also a source of surprise, because a script runs code the reader did not see.
npm run with no argument lists the scripts, which is a useful way to discover them.
The entry points
main is the CommonJS entry point. It is the older field.
module is a non-standard field that a bundler reads for an ES module entry.
browser is a non-standard field that a bundler reads for a browser build.
exports is the modern field. It is a map that declares which files are exposed and under which conditions.
{
"exports": {
".": {
"import": "./dist/index.mjs",
"require": "./dist/index.cjs",
"types": "./dist/index.d.ts"
},
"./package.json": "./package.json"
}
}
The conditions are resolved in order. A bundler that supports import gets the ESM build, and a CommonJS consumer gets the CJS build.
exports restricts access. A file that is not listed cannot be imported, which turns an internal module into a private one. This is a breaking change for a consumer that imported a deep path.
types points at the type declarations, which is what a TypeScript consumer reads.
Module type
type: "module" makes a .js file in the package an ES module.
{
"type": "module"
}
Without it, a .js file is CommonJS.
The extensions override the field. A .mjs file is always an ES module, and a .cjs file is always CommonJS, regardless of type.
The practical consequence: a package that sets type: module and has a .js file that uses require fails at runtime. The fix is to rename the file to .cjs or to convert it.
Publishing a package
A package that is published has a few extra concerns. The files field limits what is included, which keeps the tarball small and prevents a test fixture or a secret from being published. The publishConfig field can set the registry and the access level, which is how a scoped package is published as public. The prepublishOnly script runs before a publish, which is the place to run a build and a test so a broken version is not released. The version field is the source of truth for the release, and a tool such as npm version updates it and creates a git tag in one step. A package that is published should also have a license, a repository, and a README, because those are what a consumer sees on the registry page.
Common mistakes
A runtime package in devDependencies. The production install skips it and the application fails to start.
A * version range. A major update is allowed, which can break the build.
A missing lockfile. Two machines resolve different versions from the same manifest.
type: module with a require in a .js file. The file fails at runtime. Rename it to .cjs.
An exports map that omits ./package.json. A tool that reads the manifest cannot find it, which breaks some tooling.
A pre hook that is not obvious. A script runs code the reader did not see, which makes a build harder to reason about.
A missing private: true on an application. An accidental npm publish uploads the application.
A quotable summary
package.json is the manifest of a Node project: it names the package, declares its dependencies, defines its scripts, and controls how a consumer resolves it. A runtime package belongs in dependencies and a build or test package in devDependencies. A caret allows a minor update and a tilde a patch, and the lockfile pins the actual version. The exports field is the modern entry-point map and it restricts what a consumer can import, and type: module makes a .js file an ES module.
Related reading
For the managers, see npm-vs-yarn-vs-pnpm and for the modules, javascript-modules-guide. For the broader context, javascript-performance-tips and dependency-vulnerability-scanning.