package.json Cheat Sheet

General Information Fields

Field	Description	Example
name	The name of your project or package. Must be lowercase and URL-friendly.	"name": "my-app"
version	Version number for your package. Follows semantic versioning (semver).	"version": "1.0.0"
description	Short description of the project.	"description": "A web app for managing tasks"
author	Name and email of the author.	"author": "John Doe <john@example.com>"
license	License for the project (e.g., MIT, ISC).	"license": "MIT"
private	Set to true to prevent package from being published to npm registry.	"private": true
repository	The location of the project’s source code. Can be a Git repository.	"repository": { "type": "git", "url": "git+https://github.com/user/repo.git" }
homepage	URL to the project's homepage.	"homepage": "https://example.com"
keywords	Array of keywords that describe the package for search purposes.	"keywords": ["tasks", "management", "web"]

---

Scripts

Field	Description	Example
scripts	Defines custom scripts that can be run via npm run.	"scripts": { "start": "node index.js", "test": "jest" }
Common Scripts	Predefined scripts often included in package.json.	start, test, build, lint, prepublish, postinstall

---

Dependencies

Field	Description	Example
dependencies	Lists runtime dependencies needed for the project to work.	"dependencies": { "express": "^4.17.1" }
devDependencies	Lists development dependencies used for testing, building, etc.	"devDependencies": { "jest": "^27.0.0" }
peerDependencies	Specifies packages that your package needs to work correctly but won't automatically install.	"peerDependencies": { "react": "^17.0.0" }
optionalDependencies	Dependencies that are optional. These won't break the package if missing.	"optionalDependencies": { "fsevents": "^1.2.7" }
bundledDependencies	A list of packages that will be bundled when publishing your package.	"bundledDependencies": [ "module1", "module2" ]
engines	Specifies which versions of Node.js and npm your package is compatible with.	"engines": { "node": ">=12", "npm": ">=6" }
resolutions	Overrides versions of nested dependencies for Yarn (useful for fixing vulnerabilities).	"resolutions": { "lodash": "^4.17.20" }

---

Versioning and Semver

Symbol	Meaning	Example
^	Allows updates to the most recent minor version.	"express": "^4.17.1" (compatible with 4.x.x, but not 5.x.x)
~	Allows updates to the most recent patch version.	"express": "~4.17.1" (compatible with 4.17.x, but not 4.18.x)
>=	Specifies a minimum version.	"express": ">=4.17.1"
<	Specifies a maximum version.	"express": "<5.0.0"
*	Allows any version.	"express": "*"

---

Configurations for Publishing

Field	Description	Example
files	Specifies which files should be included when the package is published.	"files": ["dist/", "index.js"]
main	Entry point for the module when it's required by another application.	"main": "index.js"
bin	Define executable files that should be installed globally via npm install -g.	"bin": { "my-cli": "./bin/cli.js" }
type	Sets the module type, either module (for ES modules) or commonjs.	"type": "module"
exports	Defines which module files should be exported when using import or require.	"exports": { ".": "./index.js", "./lib": "./lib/index.js" }
browser	Defines a browser-compatible version of the module.	"browser": "browser.js"

---

Package Versioning and Hooks

Field	Description	Example
version	Version number of the package, following semantic versioning (semver).	"version": "1.0.0"
preversion	Hook that runs before a version is bumped.	"scripts": { "preversion": "npm test" }
version	Hook that runs after the version is bumped but before it is committed.	"scripts": { "version": "npm run build" }
postversion	Hook that runs after the version is committed and tagged.	"scripts": { "postversion": "git push && git push --tags" }

---

Additional Fields

Field	Description	Example
bugs	Where to report issues related to the project.	"bugs": { "url": "https://github.com/user/repo/issues" }
contributors	List of contributors to the project.	"contributors": [{ "name": "Jane Doe", "email": "jane@example.com" }]
funding	Provides information on how to financially support the project.	"funding": "https://patreon.com/user"
workspaces	List of directories for Yarn or npm workspaces, useful in monorepos.	"workspaces": ["packages/*"]
eslintConfig	Specify ESLint configuration settings directly in package.json.	"eslintConfig": { "extends": "eslint:recommended", "env": { "node": true } }

---

Common Custom Fields

Field	Description	Example
babel	Define Babel configuration in package.json instead of a separate file.	"babel": { "presets": ["@babel/preset-env"] }
jest	Configure Jest testing framework settings.	"jest": { "testEnvironment": "node" }
eslintConfig	Define ESLint settings.	"eslintConfig": { "extends": "airbnb" }
browserslist	Define the browsers that should be supported.	"browserslist": ["> 1%", "last 2 versions"]

---

Example package.json

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "A simple Node.js app",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "jest"
  },
  "author": "John Doe",
  "license": "MIT",
  "dependencies": {
    "express": "^4.17.1"
  },
  "devDependencies": {
    "jest": "^27.0.0"
  }
}