Builder Toolkit · 03 / 11

Node and npm

Understand what Node runs, what npm installs, and what package.json, node_modules, and the lockfile actually do.

Node and npm

What this is

Node is the program that runs JavaScript on your computer instead of inside a web page.

npm is the tool that comes with Node and downloads code other people wrote so you do not have to write it yourself.

The one idea

Node is the engine. npm is the parts shop. package.json is the parts list for your project.

Why it matters

You have already typed npm install and npm run dev. Those commands worked, and nothing explained what they did.

That is fine until something breaks. When a build fails with a package error, or a project works on your laptop but not on a classmate's, the fix is obvious if you know what these pieces are and impossible to guess if you do not.

What to do

Confirm what is installed

Run both of these:

Terminal command

node -v
npm -v

Swipe sideways if a command is long.

Each should print a version number such as v22.11.0. If either says the command is not found, Node is not installed or the terminal was opened before installing it.

Restart after installing

A terminal opened before you installed Node keeps the old settings. Close it and open a new one, otherwise the version check keeps failing even though the install worked.

Installing Node for a live class is covered step by step in the KDBM Lite Setup Gate. This page explains what you installed and why.

Learn the four pieces

Piece	What it actually is	What you do with it
Node	Runs JavaScript outside the browser	Nothing directly. Other commands use it.
npm	Downloads and manages packages	`npm install`, `npm run`
`package.json`	Your project's parts list and command list	Read it to see what the project uses.
`node_modules`	The downloaded packages themselves	Never edit it. Never upload it.
`package-lock.json`	Records the exact versions that were installed	Keep it. Commit it. Do not edit by hand.

Understand the two commands you already use

npm install reads package.json, downloads every listed package into node_modules, and writes the exact versions into package-lock.json.

npm run dev looks in the scripts section of package.json and runs whatever dev is defined as. The command is not built into npm. The project author chose it.

Open your own package.json and look at scripts. Every command your project supports is listed there.

Do this now

Open package.json in your editor and read the scripts block out loud. Those are the only run commands your project has.

Check yourself

node -v and npm -v both print versions.
I can find package.json in my project.
I can name one script listed in it.
I know node_modules is downloaded, not written by me.

Know when to delete node_modules

If installs behave strangely, the standard reset is to delete the downloaded packages and install again:

Terminal command

rm -rf node_modules
npm install

Swipe sideways if a command is long.

On Windows without a Unix-style terminal, delete the node_modules folder in your file explorer, then run npm install.

This is safe. Everything in node_modules can always be downloaded again from package.json. That is exactly why it must never be uploaded to GitHub.

If install fails

Read the first red line, not the last. Most npm failures name the actual problem at the top and then print pages of consequences. Work through Reading errors.

Common mistakes

Editing files inside node_modules. Your changes vanish on the next install.
Uploading node_modules to GitHub. It is huge and completely unnecessary.
Deleting package-lock.json to fix an error. That removes the record of what worked.
Running npm run dev in the wrong folder and reading the error as a code problem.
Assuming npm run dev is a universal command. It only exists if the project defines it.

Next step

Your project runs locally. Now get it off your laptop with GitHub Basics.