package-lock.json and deterministic installs in Node.js - Step-by-Step Execution

Concept Flow - package-lock.json and deterministic installs

Start: npm install

↓

Check package-lock.json

Yes↓

Use exact versions from package-lock.json

↓

Install dependencies exactly

↓

Update node_modules folder

↓

Finish: deterministic install

No↓

Create package-lock.json with resolved versions

↓

Install dependencies

↓

Finish: deterministic install

When running npm install, npm checks for package-lock.json to install exact versions, ensuring consistent installs across machines.

Execution Sample

Node.js

npm install
# Reads package-lock.json
# Installs exact versions
# Updates node_modules

This runs npm install, which uses package-lock.json to install exact dependency versions.

Execution Table

Step	Action	Check package-lock.json	Install Version	node_modules Update
1	Start npm install	Exists	Use versions from package-lock.json	Prepare node_modules
2	Resolve dependencies	Yes	Exact versions locked	Lock versions to install
3	Download packages	Yes	Exact versions	Add packages to node_modules
4	Finish install	Yes	All exact versions installed	node_modules ready
5	Run npm install again	Yes	Skip re-download if unchanged	node_modules unchanged
6	Delete package-lock.json	No	Resolve latest versions	node_modules updated with latest
7	Create new package-lock.json	No	Lock new versions	node_modules updated
8	Finish install	No	Versions may vary	node_modules ready

💡 npm install stops after installing all dependencies exactly as locked in package-lock.json or creates it if missing

Variable Tracker

Variable	Start	After Step 2	After Step 4	After Step 6	After Step 8
package-lock.json	Exists	Exists	Exists	Deleted	Created
Installed Versions	N/A	Exact locked	Exact locked	Latest resolved	Latest resolved
node_modules	Empty or outdated	Updating	Updated exact	Updating	Updated latest

Key Moments - 3 Insights

Why does npm install use exact versions from package-lock.json instead of package.json?

Because package-lock.json records the exact versions resolved, npm uses it to ensure everyone installs the same versions, as shown in execution_table rows 2 and 3.

What happens if package-lock.json is deleted before running npm install?

npm will resolve the latest versions allowed by package.json and create a new package-lock.json, as seen in execution_table rows 6 and 7.

Does npm install always download packages every time?

No, if package-lock.json and node_modules are unchanged, npm skips downloading, shown in execution_table row 5.

Visual Quiz - 3 Questions

Look at the execution_table, at which step does npm install skip re-downloading packages if nothing changed?

A Step 5

B Step 6

C Step 3

D Step 8

💡 Hint

Check the 'Install Version' and 'node_modules Update' columns at step 5 in execution_table

According to variable_tracker, what is the state of package-lock.json after step 6?

A Created

B Deleted

C Exists

D Empty

💡 Hint

Look at the 'package-lock.json' row under 'After Step 6' in variable_tracker

If package-lock.json is missing, what does npm install do according to execution_table?

A Installs exact locked versions

B Fails with error

C Resolves latest versions and creates package-lock.json

D Skips installation

💡 Hint

See steps 6 and 7 in execution_table for actions when package-lock.json is not found

Concept Snapshot

npm install uses package-lock.json to install exact dependency versions.
If package-lock.json is missing, npm resolves latest versions and creates it.
This ensures deterministic installs across machines.
Re-running npm install skips downloads if nothing changed.
package-lock.json locks versions for consistent builds.

Full Transcript

When you run npm install, npm first checks if package-lock.json exists. If it does, npm installs the exact versions recorded there, ensuring everyone gets the same dependencies. This updates the node_modules folder with those exact versions. If package-lock.json is missing, npm resolves the latest versions allowed by package.json, installs them, and creates a new package-lock.json to lock those versions. If you run npm install again without changes, npm skips downloading packages to save time. This process guarantees deterministic installs, meaning your project dependencies stay consistent across different machines and times.

Practice

1. What is the main purpose of the package-lock.json file in a Node.js project?

easy

A. To store user credentials for npm registry

B. To list all available npm packages globally

C. To configure environment variables for the project

D. To lock exact versions of installed packages for consistent installs

Solution

1. Step 1: Understand the role of package-lock.json

   This file records the exact versions of all installed packages and their dependencies.

2. Step 2: Compare with other options

   Options A, B, and D describe unrelated functions not handled by package-lock.json.

3. Final Answer:

   To lock exact versions of installed packages for consistent installs -> Option D

4. Quick Check:

   Locking versions = C [OK]

Hint: Remember: lock file fixes versions to avoid surprises [OK]

Common Mistakes:

• Confusing package-lock.json with package.json
• Thinking it stores user or environment info
• Assuming it lists global packages

2. Which command should you run to install packages exactly as specified in package-lock.json without updating it?

easy

A. npm ci

B. npm update

C. npm init

D. npm install

Solution

1. Step 1: Identify the command for deterministic installs

   npm ci installs packages exactly as locked in package-lock.json without modifying it.

2. Step 2: Understand other commands

   npm install may update the lock file; npm update upgrades packages; npm init initializes a new project.

3. Final Answer:

   npm ci -> Option A

4. Quick Check:

   Deterministic install = npm ci [OK]

Hint: Use npm ci for exact installs, no changes [OK]

Common Mistakes:

• Using npm install which can update lock file
• Confusing npm update with install
• Thinking npm init installs packages

3. Given a project with package-lock.json committed, what happens when a teammate runs npm install on their machine?

medium

A. They install latest package versions ignoring package-lock.json

B. They install exact package versions locked in package-lock.json

C. They only install packages listed in package.json without lock file

D. They get an error because package-lock.json is ignored

Solution

1. Step 1: Understand npm install behavior with package-lock.json

   When package-lock.json exists, npm install installs the exact versions locked in it to keep consistency.

2. Step 2: Evaluate other options

   Installing latest package versions ignoring package-lock.json is wrong because npm install respects the lock file. Only installing packages listed in package.json without considering the lock file is incorrect. No error occurs because of the package-lock.json file.

3. Final Answer:

   They install exact package versions locked in package-lock.json -> Option B

4. Quick Check:

   Install respects lock file = A [OK]

Hint: Lock file guides install versions unless deleted [OK]

Common Mistakes:

• Assuming npm install ignores package-lock.json
• Thinking it installs latest versions always
• Believing npm install errors if lock file exists

4. You run npm ci but get an error saying the package-lock.json file is missing. What is the likely cause?

medium

A. You forgot to commit package-lock.json to the repository

B. npm ci requires package.json only, not package-lock.json

C. Your Node.js version is too old to support npm ci

D. You need to run npm install first to generate package.json

Solution

1. Step 1: Understand npm ci requirements

   npm ci requires a valid package-lock.json file to install exact versions.

2. Step 2: Identify cause of missing lock file error

   If the lock file is missing, it is often because it was not committed or shared in the project repository.

3. Final Answer:

   You forgot to commit package-lock.json to the repository -> Option A

4. Quick Check:

   Missing lock file = forgot to commit [OK]

Hint: Always commit package-lock.json for npm ci [OK]

Common Mistakes:

• Thinking npm ci works without lock file
• Assuming Node.js version causes this error
• Confusing package.json with lock file

5. You want to ensure your CI/CD pipeline installs dependencies exactly as your team tested, avoiding any version drift. Which approach best achieves this?

hard

A. Run npm update before every build to get latest packages

B. Run npm install and commit package.json only

C. Run npm ci and commit both package.json and package-lock.json

D. Delete package-lock.json and run npm install fresh each time

Solution

1. Step 1: Identify the goal of deterministic installs in CI/CD

   To avoid version drift, installs must use exact versions tested by the team.

2. Step 2: Choose the correct commands and files to commit

   npm ci installs exactly from package-lock.json, so committing both files and using npm ci ensures consistency.

3. Step 3: Evaluate other options

   Run npm install and commit package.json only risks version drift; C updates packages which breaks consistency; D removes lock file causing unpredictable installs.

4. Final Answer:

   Run npm ci and commit both package.json and package-lock.json -> Option C

5. Quick Check:

   CI consistency = npm ci + commit lock file [OK]

Hint: Use npm ci with committed lock file for CI [OK]

Common Mistakes:

• Not committing package-lock.json
• Using npm install in CI causing version drift
• Running npm update in CI builds