NPM (Node Package Manager) and the package.json file are inseparable companions.

They’re the foundation of every Node.js project, from simple React apps to full-fledged back-end systems built with Express or NestJS.

If you’ve ever installed a library using commands like npm install react or seen a mysterious node_modules folder balloon to hundreds of megabytes, then you’ve already been working with NPM, whether you realized it or not.

But what exactly does NPM do?

What’s inside that package.json file?

And why are some dependencies marked with weird symbols like ^, ~, or *?

In this guide, we’ll break down everything you need to know about:

How NPM works
The anatomy of package.json
Installing and managing dependencies
Local vs global installation
Semantic versioning in depth (^, ~, *)
Commands for updating, uninstalling, and checking outdated packages
The importance of package-lock.json
And how to automate tasks with NPM scripts

By the end, you’ll not only understand NPM, you’ll master it.

What is NPM?

NPM stands for Node Package Manager, it’s the world’s largest software registry for JavaScript packages.

It allows developers to:

Install third-party libraries (like React, Express, Tailwind, etc.)
Manage dependencies efficiently
Share and publish their own packages.

When you install Node.js, NPM is included automatically. You can verify its installation using:

npm -v

When you run:

npm install express

NPM connects to the NPM Registry, downloads the express package and all its dependencies, and places them in your project’s node_modules folder.

The Role of `package.json`

Every Node.js project has a package.json file at its root, which is the manifest file for your project.

It contains metadata (like name and version), lists of dependencies, and project configuration.

Here’s a simple example:

{

"name": "my-awesome-app",

"version": "1.0.0",

"description": "A sample project to demonstrate npm",

"main": "index.js",

"scripts": {

"start": "nodemon index.js"

},

"dependencies": {},

"devDependencies": {}

}

You can create this file manually, but the easiest way is with:

npm init

This command will ask you for details like project name, version, entry point, and author.

To skip the questions, use:

npm init -y

The -y flag automatically accepts all default options and generates a standard package.json.

Types of Packages in NPM

NPM packages fall into two main categories:

1. Dependencies

These are libraries your app needs to run in production.

For example, if you’re using Express to handle routing:

npm install express

This installs Express and adds it to the "dependencies" section in your package.json.

It will appear in package.json as:

"dependencies": {

"express": "^4.18.2"

}

2. Dev Dependencies

These are tools you only need during development, such as testing, linting, or build tools.

Example:

npm install --save-dev nodemon

or the short version:

npm i -D nodemon

This adds nodemon under "devDependencies".

It’ll show up as:

"devDependencies": {

"nodemon": "^3.0.1"

}

💡 Pro Tip:

In modern NPM versions, --save is implicit. You don’t need to add it anymore — running npm install automatically saves dependencies to your package.json.

Local vs Global Installation

Local Installation (Default)

By default, NPM installs packages locally, meaning they’re stored inside your project folder (node_modules).

npm install lodash

This allows each project to use its own version of the package — preventing version conflicts between projects.

You can import it into your code:

const _ = require('lodash');

Global Installation

Global installation makes a package available system-wide so that you can use it from the command line anywhere.

Example:

npm install -g nodemon

This installs nodemon globally so that you can use it in any project via:

nodemon index.js

Comparison table showing local vs global installation scope.

Feature	Local Installation (e.g., npm install <package>)	Global Installation (e.g., npm install -g <package>)
Location	Inside `node_modules` folder in your project directory	System-wide directory (e.g., `/usr/local/lib/node_modules` on Unix)
Accessibility	Only available within the project where it was installed	Accessible from any directory on your system via the command line
Use Case	Project Dependencies: Libraries, frameworks, or tools that your specific project needs to run (e.g., React, Express, Lodash)	Command Line Tools (CLIs): Utilities you want to run from any terminal location (e.g., `nodemon`, `create-react-app`, `vue-cli`, `http-server`)
`package.json`	Listed in `dependencies` or `devDependencies`	Not listed in any `package.json` unless it's a dev dependency for another global tool
Version Control	Managed per project; different projects can use different versions of the same package.	One version is installed system-wide; changes might affect multiple projects if they rely on specific global versions
Isolation	Highly isolated; prevents conflicts between different projects needing different package versions.	Less isolated; potential for version conflicts if global tools have conflicting dependencies or if multiple projects need different global tool versions
Execution	Usually run via scripts defined in `package.json` (e.g., `npm run build`) or by explicitly referencing their path (`./node_modules/.bin/webpack`)	Run directly from the terminal by typing the package's command name (e.g., `nodemon app.js`)
Example	`npm install react`	`npm install -g nodemon`

The `node_modules` Folder

The node_modules folder stores all your installed packages and their dependencies — it’s the “library shelf” for your project.

You’ll never manually edit this folder.

Instead, you use NPM commands to modify it:

npm install → Installs missing dependencies
npm uninstall package-name → Removes packages
npm update → Updates to newer versions

If deleted, you can always regenerate it by running:

npm install

and NPM will rebuild it using your package.json and package-lock.json.

The `package-lock.json` File

The package-lock.json file is automatically created when you run npm install.

It records:

The exact version of each dependency (and sub-dependency)
Their download URLs
A unique integrity hash for verification

This ensures that every developer working on the project gets identical versions, preventing “it works on my machine” issues.

You should always commit package-lock.json to version control (like Git) as it’s essential for team consistency.

Semantic Versioning Explained (`^`, `~`, `*`)

Every NPM package follows Semantic Versioning (SemVer), written as:

major.minor.patch

Example:

1.18.11

1 → Major: Big changes that might break compatibility
18 → Minor: New features that don’t break existing code
11 → Patch: Bug fixes or minor improvements

Now, let’s break down those symbols you often see in package.json.

1. The Caret (^)

Example:

"express": "^4.18.2"

The caret allows minor and patch updates, but prevents breaking major changes.

✅ Will update to → 4.19.0 or 4.18.5

❌ Will NOT update to → 5.0.0 (major)

This is the most common and safest symbol used in production projects.

Think of it as: “Keep me up-to-date as long as nothing breaks.”

2. The Tilde (~)

Example:

"lodash": "~4.17.21"

The tilde allows only patch updates, not minor or major ones.

✅ Will update to → 4.17.22

❌ Will NOT update to → 4.18.0

This is great when you want stability, like when your app is sensitive to changes.

Think of it as: “Only fix bugs, don’t add new features.”

3. The Asterisk (*)

Example:

"react": "*"

The asterisk means any version is acceptable.

It tells NPM: “Install whatever is the latest available.”

⚠️ Caution: This can break your app if a new major version introduces breaking changes.

Think of it as: “I’ll take whatever you have, hope it works!”

4. Exact Versions

You can also lock a dependency to an exact version:

"axios": "1.6.8"

NPM will always install the exact version 1.6.8 , no updates unless you change it manually.

Checking and Managing Package Versions

Check outdated packages:

npm outdated

This displays a table showing:

The current version
The wanted version (based on semver range)
The latest available version

Update packages:

npm update

This upgrades all packages allowed by your semver rules (^ and ~).

For Example:

npm update express

This updates express to the latest version allowed by your semver range.

Install a specific version:

You can install a specific version of a package like this:

npm install express@4.17.3

This ensures your project always uses that exact version.

Uninstall a package:

npm uninstall express

This removes the package from both node_modules and package.json.

The Power of NPM Scripts

Inside package.json, the scripts section lets you define shortcuts for repetitive commands.

Example:

"scripts": {

"start": "nodemon index.js",

"test": "jest",

"build": "webpack --mode production",

"dev": "vite"

}

You can run any script with:

npm run <script-name>

For example:

npm run start

Some scripts, like start and test, can be run without run:

npm start

npm test

This makes development workflows smooth and automated.

Common scripts include:

"test" → for running tests
"build" → for building production bundles
"dev" → for running a development server

Conclusion

NPM and the package.json file are at the heart of every modern JavaScript project.

They manage your dependencies, automate scripts, and ensure consistent environments across development and production.

By mastering concepts like versioning, installation types, and scripts, you’ll have the control needed to build scalable and maintainable applications.