Node.js package.json

The package.json file is the identity card of a Node.js project. It stores the project name, version, scripts, and the list of libraries the project needs. Every Node.js project carries one.

Why the File Matters

Imagine a recipe card that lists the dish name and every ingredient. A friend reads the card and cooks the same dish. The package.json file plays that role. Another developer reads it and installs the same libraries with one command.

Create the File

Run this command inside your project folder.

npm init -y

The -y flag accepts all default answers. Skip the flag to answer each question yourself.

A Sample File

{
  "name": "shop-api",
  "version": "1.0.0",
  "description": "A simple shop API",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "test": "jest"
  },
  "dependencies": {
    "express": "^4.19.2"
  },
  "devDependencies": {
    "nodemon": "^3.1.0"
  },
  "author": "Your Name",
  "license": "MIT"
}

Understand Each Field

name and version

The name field uses lowercase letters with no spaces. The version field follows a three-number pattern explained below.

description and author

These fields tell readers what the project does and who built it.

main

The main field names the entry file. Node.js loads this file when another project imports yours.

scripts

The scripts field holds shortcuts for long commands. Run a script with npm run name. The names start and test also work without the word run.

npm start
npm test
npm run dev

dependencies

This section lists libraries your app needs while it runs. Express belongs here.

devDependencies

This section lists tools you need only while you build and test. Nodemon and Jest belong here. Production servers skip them.

package.json
   |
   +-- dependencies     --> needed when the app runs
   |      express, mongoose
   |
   +-- devDependencies  --> needed when you build
          nodemon, jest

license

The license tells others how they may use your code. MIT is a popular open choice.

Read the Version Numbers

Versions use three numbers called semantic versioning.

      4  .  19  .  2
      |     |      |
   Major  Minor  Patch

• Major changes can break old code.
• Minor changes add features and keep old code working.
• Patch changes fix bugs.

Caret and Tilde Symbols

• ^4.19.2 allows minor and patch updates, such as 4.20.0.
• ~4.19.2 allows patch updates only, such as 4.19.5.
• 4.19.2 locks the exact version.

Add and Remove Libraries

npm install express              // adds to dependencies
npm install nodemon --save-dev   // adds to devDependencies
npm uninstall express            // removes the library

Each command updates package.json for you. Avoid editing the dependency lists by hand.

The package-lock.json File

Npm creates a second file named package-lock.json. This file records the exact version of every library, including the libraries your libraries use. Share it through version control so every teammate installs identical versions.

Share a Project

Never copy the node_modules folder. The folder grows huge and rebuilds from package.json in seconds. Share only your code, package.json, and package-lock.json. Add this line to a .gitignore file.

node_modules/

A teammate downloads your project and runs one command.

npm install

Your project            Teammate's computer
+--------------+        +--------------------+
| index.js     |  copy  | index.js           |
| package.json | -----> | package.json       |
| lock file    |        | npm install        |
+--------------+        |  --> node_modules  |
                        +--------------------+

Practice Tasks

• Create a new folder and run npm init -y.
• Install Express and check where it appears in package.json.
• Add a script named hello that prints a message, then run it.