package.json

Introduction to package.json

The package.json file is the heart of any Node.js project. It acts as a manifest file for the project, holding metadata, dependencies, scripts, and other configuration settings required to manage the project efficiently. Without it, npm or yarn cannot install dependencies, run scripts, or share your project.

Think of it as a blueprint for your project.

Basic Structure of package.json

A minimal package.json may look like this:

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "A sample Node.js project",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "keywords": ["node", "npm", "package"],
  "author": "Harsha",
  "license": "MIT"
}

Let’s break down each field.

Metadata Fields

1. name

• Specifies the name of the project.
• Must be lowercase, can include hyphens or underscores.
• Example: "name": "my-app"

2. version

• Defines the current version of the project.
• Follows Semantic Versioning (SemVer): MAJOR.MINOR.PATCH
  • MAJOR: Breaking changes
  • MINOR: New features without breaking changes
  • PATCH: Bug fixes
• Example: "version": "1.0.0"

3. description

• A short description of your project.
• Useful for npm registry and documentation.
• Example: "description": "A Node.js project demo"

4. keywords

• An array of keywords for discoverability in npm.
• Example: "keywords": ["node", "express", "api"]

5. author / contributors

• author: Name of the project author.
• contributors: Array of contributors.
• Example:

"author": "Harsha",
"contributors": ["Alice", "Bob"]

6. license

• Specifies the license type of your project.
• Common licenses: MIT, GPL-3.0, Apache-2.0.
• Example: "license": "MIT"

Entry Point

main

• Defines the entry point of your package when imported.
• Default is "index.js".
• Example: "main": "index.js"

type

• Determines module type: CommonJS ("type": "commonjs") or ES Module ("type": "module").
• Example: "type": "module"

Scripts

scripts

• Scripts are commands that can be run using npm run <script-name>.
• Common scripts:

"scripts": {
  "start": "node index.js",
  "dev": "nodemon index.js",
  "test": "jest",
  "build": "webpack"
}

• Can also include pre and post hooks:
  • "prestart" runs before "start"
  • "poststart" runs after "start"

Dependencies

Dependencies are external modules your project relies on.

1. dependencies

• Required for the project at runtime.
• Installed with npm install.
• Example:

"dependencies": {
  "express": "^4.18.2",
  "dotenv": "^16.0.3"
}

2. devDependencies

• Needed only for development (testing, building, linting).
• Installed with npm install --save-dev.
• Example:

"devDependencies": {
  "jest": "^29.5.0",
  "eslint": "^8.44.0"
}

3. peerDependencies

• Specifies compatible versions your package works with.
• Example:

"peerDependencies": {
  "react": "^18.0.0"
}

4. optionalDependencies

• Dependencies that are not critical; installation failures won’t break the project.
• Example:

"optionalDependencies": {
  "fsevents": "^2.3.2"
}

5. bundledDependencies

• Dependencies bundled when publishing a package.
• Example:

"bundledDependencies": ["lodash"]

Versioning and Resolutions

1. Version Prefixes

• ^1.2.3: Compatible with 1.x.x versions ≥1.2.3.
• ~1.2.3: Compatible with 1.2.x versions ≥1.2.3.
• 1.2.3: Exact version.

2. engines

• Specifies compatible Node.js/npm versions.
• Example:

"engines": {
  "node": ">=18.0.0",
  "npm": ">=9.0.0"
}

Repository & Bugs

• repository: Links to the source code.

"repository": {
  "type": "git",
  "url": "https://github.com/username/my-app.git"
}

• bugs: Points to the issue tracker.

"bugs": {
  "url": "https://github.com/username/my-app/issues"
}

• homepage: URL of the project homepage.

"homepage": "https://my-app.com"

Configurations & Miscellaneous

1. private

• If true, prevents publishing to npm.
• Example: "private": true

2. files

• Array of files/folders to include when publishing.
• Example:

"files": ["dist", "index.js"]

3. exports

• Specifies module entry points for ESM consumers.
• Example:

"exports": {
  ".": "./index.js",
  "./feature": "./feature.js"
}

4. bin

• Specifies executables your package exposes.
• Example:

"bin": {
  "mycli": "./cli.js"
}

5. sideEffects

• Helps tree-shaking for bundlers.
• Example:

"sideEffects": false

Advanced Fields

• scripts.prepublishOnly: Runs before publishing
• scripts.prepare: Runs both before install from Git & before publishing
• resolutions: Forces dependency versions in nested dependencies
• config: Custom key-value config for your package

"config": {
  "port": 8080
}