package.json Cheatsheet — 55+ Fields Explained with Examples

Package name — must be URL-safe, lowercase, no spaces. Hyphens and underscores are fine. Scoped packages use @scope/name format. This is the identifier users type in `npm install <name>`.

Semantic version — MAJOR.MINOR.PATCH. Required for publishing. Bump correctly: MAJOR for breaking changes, MINOR for new features, PATCH for bug fixes. Pre-release: 1.0.0-alpha.1.

One-line description shown in npm search results. Keep it factual and short — no marketing copy. Appears on the registry page and in `npm search` output.

Tags that improve discoverability in `npm search`. Think about what terms someone would search when they need what your package provides.

URL of the project website or documentation. Shown as a link on the npm registry page.

Issue tracker URL and/or contact email for bug reports. npm surfaces this as the "Report a vulnerability" link. Can be a plain URL string or an object with `url` and `email`.

SPDX license identifier. Use "MIT", "ISC", "Apache-2.0", "GPL-3.0", etc. For proprietary/private packages use "UNLICENSED" to signal no public license is granted.

Package author. Can be a "Name <email> (url)" shorthand string, or an object with `name`, `email`, and `url` keys.

List of contributors in the same format as `author`. Optional — `git log` is the canonical source of contribution history.

Source code location. npm shows a "Repository" link on the package page and enables `npm repo` to open it in a browser. Add `directory` for monorepo packages.

Financial support channels. npm shows a funding notice on install, and `npm fund` lists all packages with this field in your project.

Shell commands run via `npm run <key>`. Keys `start`, `test`, `stop`, and `restart` can omit the `run` sub-command. All scripts get node_modules/.bin on PATH automatically.

Runs before the package is packed or published, AND on local `npm install` (including git installs). Used to build output before publishing.

Runs ONLY before `npm publish`, not on install. Safer than `prepare` for publish-specific checks like running tests before releasing.

Runs after the package is installed. Widely used by native addons to compile C++ bindings. Any package's postinstall script runs automatically — review what you install.

Lifecycle hooks that fire automatically before or after `npm run <name>`. Works for ANY custom script name, not just built-ins. e.g. `prebuild` runs before `build`.

Default values accessible inside npm scripts via the `npm_package_config_<key>` environment variable. Users can override with `npm config set <pkg-name>:<key> <val>` without editing package.json.

Runtime packages. Installed when your package is installed from npm. Use semver ranges: `^` for compatible updates within the same major, `~` for patch-only updates.

Packages needed only in development (bundlers, test runners, linters, type checkers). NOT installed when users install your package from npm.

Packages consumers of your library must install themselves. Use for plugins, framework adapters, and libraries that must share an instance with the host app (react, webpack, etc.).

Metadata for each peer dependency entry. Set `{ "optional": true }` to suppress the missing-peer warning when that peer is not installed.

Packages npm tries to install but does not fail if they cannot be installed (e.g. native addons for optional features). Your code must handle their absence gracefully.

Packages bundled inside your tarball on publish. Useful when distributing a package that cannot rely on npm registry availability (offline deploys, vendor-locked packages).

Force all nested uses of a transitive dependency to a specific version. Useful for applying a security patch before the upstream maintainer publishes a fix.

Yarn's equivalent of npm `overrides`. Forces a transitive dependency to a specific version. Yarn Classic and Yarn Berry support slightly different glob syntax.

Allowlist of files/directories included when you `npm publish`. Files NOT listed are excluded. Omitting this includes everything (minus .gitignore). Always prefer `files` over .npmignore.

Prevents accidental publishing. npm will refuse any `npm publish` command when this is `true`. Must-have in application repos and monorepo roots.

Config values that only apply during `npm publish`. Common uses: point to a private registry, set the default dist-tag, or set `access` for scoped packages.

Legacy CJS entry point. Returned when someone does `require("your-package")`. Still supported by old tools and Node < 12. When `exports` is defined, Node 12+ prefers it over `main`.

Unofficial but widely supported ESM entry for bundlers (Rollup, Webpack, Vite). They prefer this over `main` to enable tree-shaking. Node.js itself does NOT use this field.

Browser-specific alternative to `main`. Bundlers swap in this file when building for browser targets. Object form remaps specific files or sets them to `false` to exclude from bundles.

Explicit package entry-point map. Defines exactly which sub-paths can be imported. Any unlisted path throws ERR_PACKAGE_PATH_NOT_EXPORTED, making internals truly private.

Named conditions inside an exports path: `"import"` for ESM import, `"require"` for CJS require(), `"browser"` for bundlers, `"types"` for TypeScript, `"default"` as the fallback.

Package self-import map. Allows your own files to use `import "#utils"` instead of deep relative paths like `../../utils`. Keys must start with `#`. Node 12.7+ only.

CLI executables symlinked into node_modules/.bin on install (and into PATH for global installs). The target file must have a `#!/usr/bin/env node` shebang.

How `.js` files are interpreted. `"module"` → ES Modules (`import`/`export`). `"commonjs"` (default) → CommonJS (`require`). Override per-file with `.mjs` or `.cjs` extensions.

`false` tells bundlers every file is pure — unused exports can be dropped (tree-shaking). An array whitelists specific files that DO have side effects.

Path to the TypeScript declaration file (.d.ts) for the package root. TypeScript checks this first when resolving types. For sub-paths, use the `"types"` condition inside `exports`.

Glob patterns pointing to local packages in a monorepo. npm/Yarn/pnpm symlink them into node_modules so they can be imported by name. Requires `"private": true` in the root.

Yarn-specific: prevents listed packages from being hoisted to the root node_modules. Used when a workspace package must have its own copy co-located (e.g. React Native).

Required Node.js (and npm/pnpm/yarn) version range. npm WARNS (not errors) if the engine doesn't match by default. Set `engine-strict=true` in `.npmrc` to make mismatches fatal.

Restrict which operating systems can install this package. Values match `process.platform`: `"linux"`, `"darwin"` (macOS), `"win32"`. Prefix with `!` to exclude.

Restrict which CPU architectures are supported. Values match `process.arch`: `"x64"`, `"arm64"`, `"ia32"`. Common for native addons that distribute prebuilt binaries.

Pin which package manager and exact version the project expects. Corepack enforces this — running the wrong manager in the project throws an error. Format: `<name>@<semver>`.

`"react": "*"` accepts ANY react version, including incompatible majors. Your library installs silently alongside React 1 or React 19. Specify a real range.

Once `exports` is set, every path not listed throws `ERR_PACKAGE_PATH_NOT_EXPORTED`. Adding `exports` to an existing package is a BREAKING CHANGE even if you only add the root `"."` entry.

If your package has `import "./globals.css"` anywhere, setting `"sideEffects": false` causes Webpack/Vite to tree-shake it away. The CSS never loads.

Without `"private": true`, a stray `npm publish` in an application repo publishes your entire app to the public registry — credentials, configs, and all.

If BOTH `files` and `.npmignore` exist, `.npmignore` is completely ignored. If neither exists, npm falls back to `.gitignore`. Always use `files` — it's explicit and version-controlled.

npm 7+ warns about missing peers but does not always install them. npm 3–6 never installed them. Users must install peers alongside your package. Document this in your README.

npm uses `overrides` (v8.3+), Yarn uses `resolutions`. They are NOT interchangeable. pnpm also uses `overrides`. Yarn Classic and Berry have different glob syntax for resolutions.

Always commit package-lock.json / yarn.lock / pnpm-lock.yaml. Without it, `npm install` may resolve different (possibly breaking) versions than what you tested.

npm only WARNS if the engine range doesn't match — it still proceeds. To make it a hard error, add `engine-strict=true` to `.npmrc` in the repo, or pass `--engine-strict`.

Putting `react` in `dependencies` of a component library gives consumers two React instances — yours and theirs. This breaks hooks (useContext, useState) and causes cryptic errors.