Understanding package.json

The package.json file is the heart of every Node.js project. It contains metadata about your project and manages your dependencies.

What is package.json?

package.json is a JSON file that:

• Identifies your project - Name, version, description
• Lists dependencies - Packages your project needs
• Defines scripts - Commands for building, testing, deploying
• Stores metadata - Author, license, repository

Every npm project needs a package.json file. Without it, npm doesn't recognize your folder as a project.

Anatomy of package.json

Here's a complete example with all common fields:

Required Fields

Only two fields are truly required for publishing to npm:

name

The package name must be:

• Lowercase
• One word (no spaces)
• May contain hyphens and underscores
• Unique on npm (if publishing)

{
  "name": "my-project"
}

version

Must follow semantic versioning:

{
  "version": "1.0.0"
}

Format: MAJOR.MINOR.PATCH

Common Fields

description

A brief description of your project:

{
  "description": "A fast and reliable web server"
}

main

The entry point of your application:

{
  "main": "index.js"
}

When someone require()s your package, this file is loaded.

scripts

Commands you can run with npm run:

{
  "scripts": {
    "start": "node server.js",
    "test": "jest",
    "build": "webpack"
  }
}

keywords

Help people find your package on npm:

{
  "keywords": ["web", "server", "http", "api"]
}

author

The package creator:

{
  "author": "Jane Doe <jane@example.com> (https://janedoe.com)"
}

Or as an object:

{
  "author": {
    "name": "Jane Doe",
    "email": "jane@example.com",
    "url": "https://janedoe.com"
  }
}

license

The license for your code:

{
  "license": "MIT"
}

Common licenses: MIT, ISC, Apache-2.0, GPL-3.0

Dependencies

The most important practical fields:

dependencies

Packages needed to run your application:

{
  "dependencies": {
    "express": "^4.18.2",
    "lodash": "^4.17.21"
  }
}

devDependencies

Packages needed only for development:

{
  "devDependencies": {
    "jest": "^29.7.0",
    "eslint": "^8.55.0"
  }
}

Practice: Edit package.json

Try modifying this package.json. Add a new dependency or change the description:

package.json vs package-lock.json

File	Purpose	Committed?
package.json	Your dependency requirements	Yes
package-lock.json	Exact installed versions	Yes

We'll cover package-lock.json in detail later.

Key Takeaways

1. package.json is required for all npm projects
2. name and version are the only mandatory fields
3. dependencies are packages your app needs to run
4. devDependencies are packages only needed during development
5. scripts let you define custom commands

What's Next?

In the next lesson, you'll learn how to create your own package.json using npm init.