Skip to main content

Understanding package.json in Node.js / JavaScript Projects

The package.json file is the core descriptor of a Node.js (or JavaScript-based) project. It contains metadata about the project, scripts, dependencies, and other configurations that tools like npm and yarn use to manage and run the application.

Purpose of package.json​

  • Describes the project (name, version, description, etc.)
  • Lists all packages the project depends on
  • Specifies scripts to automate tasks (build, test, start, etc.)
  • Enables reproducibility and sharing of the project
  • Provides configuration for tools like linters, bundlers, and compilers

Basic Structure​

Here is a typical package.json file:

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "A sample JavaScript project",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "vite",
    "build": "vite build",
    "test": "jest"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "devDependencies": {
    "vite": "^5.0.0",
    "jest": "^29.0.0"
  },
  "keywords": ["javascript", "node", "react"],
  "author": "Your Name",
  "license": "MIT"
}

Key Fields Explained​

name​

  • The name of your project or package.
  • Must be lowercase and URL-safe if published to npm.

version​

description​

  • A short summary of your project.

main​

  • The entry point to your application when it is required as a module.

scripts​

  • Defines command-line scripts that can be run with npm run or yarn.
  • Example:
    • npm run start → runs node index.js
    • npm run build → runs the build process

dependencies​

  • Lists packages required for the project to run.
  • These packages will be installed when someone runs npm install.

devDependencies​

  • Packages needed only during development (not in production).
  • Examples: testing libraries, bundlers, linters.

keywords​

  • An array of strings that help people find your package on npm.

author​

  • Name of the author of the package.

license​

  • Type of license (e.g., MIT, ISC, etc.)

Other Common Fields​

type​

  • Defines module type: "module" for ES modules, or "commonjs" for CommonJS. 
    "type": "module"

engines​

  • Specifies Node.js or npm version requirements. 
    "engines": {
      "node": ">=16.0.0"
    }

peerDependencies​

  • Used when your package expects the host project to provide certain dependencies.

optionalDependencies​

  • Dependencies that are not required but used if available.

private​

  • Prevents the package from being accidentally published to npm. 
    "private": true

Common Mistakes​

  • Forgetting to update the version field.
  • Adding development tools under dependencies instead of devDependencies.
  • Incorrectly structured JSON (missing commas or braces).
  • Not keeping scripts consistent or meaningful.
  • Publishing sensitive or private packages without setting "private": true.

Summary​

FieldDescription
nameProject/package name
versionProject version using semantic versioning
scriptsAutomation commands for development lifecycle
dependenciesRuntime libraries the app needs
devDependenciesBuild/test tools needed only for development
mainEntry file of the app/module
licenseOpen source license type

Resources​