Understanding package.json and package-lock.json in Node.js

You clone a Node.js project, run npm install, and everything looks fine. Then you start the app and something behaves differently than expected. A teammate says it works perfectly on their machine. The code is the same. The configuration is the same. So what changed? Most of the time, the answer is simple: the dependencies are different. To understand why this happens, you need to understand two core files in every Node.js project: package.json and package-lock.json. They look similar, but they serve completely different purposes.

Why Dependency Management Exists

Modern JavaScript applications rely heavily on external libraries. Instead of writing everything from scratch, developers install packages from npm. But each package can depend on other packages. Those packages can depend on even more. This creates a dependency tree that can quickly become large and complex. Managing that tree manually would be nearly impossible. That is why npm uses configuration files to define and control how dependencies are installed. The package.json file describes what your project needs. The package-lock.json file records exactly what was installed. You need both for stable and predictable development.

What Is package.json

The package.json file is the main configuration file for a Node.js project. It defines metadata about your project and lists the dependencies it requires. You usually create it with:

npm init

Or automatically:

npm init -y

Here is a simple example:

{
  "name": "my-server",
  "version": "1.0.0",
  "description": "A simple Node.js application",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "node index.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  }
}

Project Metadata

Fields like name, version, and description identify your project. The main field tells Node which file is the entry point.

Scripts

The scripts section allows you to define commands such as:

npm start
npm run dev

These scripts help standardize how your project runs.

Dependencies

The dependencies section lists packages required for your application to work in production. When you run:

npm install express

npm automatically adds Express to this section. But the version format matters.

Understanding Version Ranges

In this example:

"express": "^4.18.2"

The caret symbol allows npm to install newer minor and patch versions within the same major version. Node packages follow semantic versioning. A version like 4.18.2 has three parts: Major version changes introduce breaking changes. Minor version changes add new features without breaking compatibility. Patch version changes fix bugs. The caret ^ allows updates such as 4.19.0 or 4.20.1, but not 5.0.0. If you use a tilde:

"express": "~4.18.2"

Only patch updates like 4.18.3 are allowed. If you write:

"express": "4.18.2"

Only that exact version will be used. This flexibility is convenient, but it introduces uncertainty. That uncertainty is solved by package-lock.json.

What Is package-lock.json

The package-lock.json file is automatically generated when you run npm install. You should never edit it manually. While package.json defines version ranges, package-lock.json records the exact versions that were installed, including every nested dependency. For example, if you install Express, Express itself depends on multiple internal packages. Those internal packages may depend on others. The entire dependency tree is stored in package-lock.json. This ensures that every time someone runs npm install, the exact same versions are installed. It makes installations deterministic.

How package.json and package-lock.json Work Together

These two files are not duplicates. They have different responsibilities. package.json describes what your project needs and what versions are acceptable. package-lock.json freezes the exact dependency tree that was resolved during installation. When you run npm install in a project that already has a lock file, npm installs the exact versions listed there. It does not search for newer compatible versions. When you add a new dependency, npm updates both files automatically. If you delete the lock file and run npm install again, npm re-resolves versions based on the ranges in package.json. This may result in different versions being installed. That is why the lock file is important for stability.

A Simple Example in Practice

Let us create a small Express server to see how this works. First, initialize the project:

npm init -y

Then install Express:

npm install express

Now create a file called index.js:

// Import express
const express = require('express');

// Create an Express app
const app = express();

// Define a route
app.get('/', (req, res) => {
  res.send('Hello, world!');
});

// Start the server
app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Run the application:

npm start

If someone else clones your project and runs npm install, they will get the exact same dependency versions recorded in package-lock.json. The behavior will remain consistent.

Development Dependencies

Not all dependencies are needed in production. Some are used only during development. For example, install Nodemon for automatic server restarts:

npm install --save-dev nodemon

Your package.json will now include:

{
  "devDependencies": {
    "nodemon": "^3.0.1"
  }
}

These packages are used only during development. The lock file still records their exact versions, ensuring consistency across environments.

Best Practices

Always commit both package.json and package-lock.json to version control. Never manually edit package-lock.json. If you need to reset dependencies, delete node_modules and package-lock.json, then run npm install again. For automated environments like CI pipelines, use:

npm ci

This command installs dependencies strictly from the lock file and fails if there are inconsistencies.

Why This Matters

In small projects, version differences might not seem important. In larger applications or team environments, inconsistent dependencies can cause subtle and difficult-to-debug issues. The combination of package.json and package-lock.json ensures that what you test locally is exactly what runs in production. Once you understand how these files work together, you gain control over your project’s environment instead of leaving it to chance.