Comprehensive Guide to package.json Configuration in Frontend Projects

1. Required fields

The most essential fields in package.json are name and version . The name must be less than 214 characters, lowercase, and cannot start with "." or "_"; it should be short and semantic. The version follows semantic versioning (major.minor.patch) and may include pre‑release tags such as alpha , beta , or rc .

name

Examples of a valid name field:

{
  "name": "my-app",
  "version": "0.1.0",
  "private": true
}

version

Typical version strings look like 1.2.3 . You can view the latest version of a package with:

// view latest version
npm view react version
// view all versions
npm view react versions

2. Description fields

Package metadata that helps others discover the module includes:

description

A short text describing the package.

keywords

An array of strings used for search indexing.

author

Can be a string or an object. Example:

"author": "CUGGZ
(https://juejin.cn/user/3544481220801815)"

"author": {
  "name": "CUGGZ",
  "email": "[email protected]",
  "url": "https://juejin.cn/user/3544481220801815"
}

contributors

Array of strings or objects listing all contributors.

"contributors": [
  "CUGGZ0
(https://juejin.cn/user/3544481220801815)",
  "CUGGZ1
(https://juejin.cn/user/3544481220801815)"
]

"contributors": [
  {
    "name": "CUGGZ0",
    "email": "[email protected]",
    "url": "https://juejin.cn/user/3544481220801815"
  },
  {
    "name": "CUGGZ1",
    "email": "[email protected]",
    "url": "https://juejin.cn/user/3544481220801815"
  }
]

homepage, repository, bugs

These fields point to the project homepage, source repository, and issue tracker respectively.

3. Dependency configuration

Dependencies are split into several categories:

dependencies

Packages required at runtime. Example installation commands:

npm install <PACKAGE_NAME>
yarn add <PACKAGE_NAME>

npm install --save <PACKAGE_NAME>

devDependencies

Packages needed only during development (e.g., Webpack, Babel, ESLint). Install with:

npm install --save-dev <PACKAGE_NAME>
yarn add --dev <PACKAGE_NAME>

peerDependencies

Used by plugins to specify a compatible version of a host library. Example:

"peerDependencies": {
  "chai": "1.x"
}

optionalDependencies

Packages that may fail to install without breaking the whole installation.

bundledDependencies

An array of modules that will be bundled together when the package is published.

engines

Specifies required Node or npm versions, e.g.:

"engines": {
  "node": ">=8.10.3 <12.13.0",
  "npm": ">=6.9.0"
}

4. Scripts configuration

The scripts field defines command‑line shortcuts that can be run with npm run . Prefixes pre and post allow hook scripts.

"scripts": {
  "dev": "node index.js",
  "predev": "node beforeIndex.js",
  "postdev": "node afterIndex.js"
}

Running npm run dev prints:

scripts: before index.js
scripts: index.js
scripts: after index.js

Commonly used scripts include start , test , lint , and build .

config

Custom configuration values are exposed as environment variables, e.g.:

"config": { "port": 3000 }
// accessed via process.env.npm_package_config_port

5. Files & directories

main, browser, module

Entry points for CommonJS, browser, and ES‑module builds respectively.

bin

Maps command names to executable files.

files

Array of files/folders to include when publishing.

directories

Custom paths for bin , lib , doc , test , etc.

6. Publishing configuration

Fields such as private , preferGlobal , publishConfig , os , cpu , and license control how the package is released and who can install it.

7. Third‑party configurations

Many tools allow their settings to be placed directly in package.json :

typings

Specifies the TypeScript definition entry file.

eslintConfig

ESLint rules and environment settings.

babel

Babel presets and plugins.

unpkg

Provides a CDN path for the package.

lint‑staged & gitHooks

Run linters on staged files before committing.

browserslist

Defines target browsers for tools like Babel and Autoprefixer.

For further reading, see the npm configuration documentation.