Skip to content
Velloreth
Developer Tools 6 min read

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

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

RangeAllows
1.2.3exactly 1.2.3
~1.2.31.2.x, a patch update
^1.2.31.x.x, a minor or patch update
>=1.2.3any version at or above
*any version
1.2.x1.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.

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.

Frequently asked questions

What is the difference between dependencies and devDependencies?
dependencies are packages the application needs at runtime, so they are installed in production. devDependencies are packages needed only to develop, test or build, such as a test runner or a bundler, and they are skipped in a production install. Putting a runtime package in devDependencies causes a failure in production.
What does the caret in ^1.2.3 mean?
It allows any version from 1.2.3 up to but not including 2.0.0, so a minor or patch update is allowed and a major update is not. A tilde allows a patch update only, so ~1.2.3 allows 1.2.x. An exact version allows no update. The lockfile pins the actual version regardless of the range.
What is the exports field?
It is a map that declares which files a package exposes and under which conditions. It replaces the older main and browser fields, and it can restrict a consumer to the public entry points, so an internal file cannot be imported. It is the modern way to define a package's public interface.
What does type: module do?
It makes a .js file in the package an ES module, so it uses import and export. Without it, a .js file is CommonJS and uses require. A .mjs file is always an ES module and a .cjs file is always CommonJS, regardless of the type field.
What is the difference between npm run and npx?
npm run executes a script defined in the scripts field. npx executes a package's binary, downloading it if it is not installed. Use npm run for a project script and npx for a one-off tool.
Should I commit package-lock.json?
Yes. The lockfile records the exact version and integrity hash of every package, including the transitive ones, so an install is reproducible. Without it, two machines can resolve different versions from the same package.json.