What do npm install, node_modules and package.json actually do?

What it actually is

npm is usually read as “Node Package Manager,” though npm’s own documentation is clear that isn’t actually what the letters stand for. The real story behind the name is murkier than that tidy explanation. What matters day to day is simpler: npm is the tool that fetches code other people already wrote (a login flow, a way to talk to Stripe, a set of ready-made buttons) so your AI agent doesn’t rewrite common functionality from zero every time. Each chunk of borrowed code is a “package,” and npm’s job is finding it, downloading it, and tracking which version you’re using.

Two things do the actual work. package.json is the ingredient list: a text file naming every package your project depends on and roughly which version is okay. node_modules is the pantry: the folder where those packages actually land on disk, code and all, sometimes gigabytes of it, once every package’s own dependencies get pulled in too.

npm ships bundled with Node.js itself, so it behaves identically on a Mac, a Windows machine, or Linux. Nothing about it is tied to one operating system, despite living in a terminal that can feel Linux-flavored.

Why your AI just did this

When your agent starts a new project, it usually runs something like npm init, or a scaffolding command that generates one for you (create-next-app, create-vite). That’s what produces the first package.json. From then on, every time your app needs a new capability (talking to a database, sending email, formatting dates), your agent runs npm install <package-name>. That single command does two things: it drops the code into node_modules, and it adds a line to package.json recording that your project now depends on it.

Run npm install alone, with no package name, and it does something different: it reads the existing package.json and downloads everything listed. That’s the move you’ll see your agent make right after cloning a repo or opening someone else’s project, because node_modules itself is never shared. Only the list of what belongs in it.

When you’ll run into it

You’ll see “Cannot find module ‘xyz’” or “command not found” when your code expects a package that isn’t installed yet. The fix is almost always npm install. You’ll notice node_modules listed inside .gitignore, because nobody commits it to version control; it’s rebuilt from package.json on any machine that needs it. Next to package.json you’ll spot package-lock.json, which npm writes automatically to freeze the exact version of every package (including the packages your packages depend on) so a teammate’s npm install reproduces the same setup you have. And right before your agent runs your app for the first time in a session, it’ll often say something like “installing dependencies,” which is npm quietly doing this download.

What to check

• node_modules is listed in .gitignore. It should never be committed to git
• package-lock.json IS committed. It’s what makes installs reproducible across machines
• Before installing an unfamiliar package, glance at its npm page for download counts and last-updated date. A barely-used or long-abandoned package is a bigger risk
• After npm install, skim the terminal output for “found N vulnerabilities” and run npm audit if anything gets flagged
• If a package tries to run its own “postinstall” script during install, be cautious about installing obscure ones. That’s a real place malicious code can hide

Say it like a dev

Instead of: “the app is broken, it says some module can’t be found” Say: “I’m getting ‘Cannot find module.’ Can you run npm install and check package.json for what’s missing?”

Instead of: “add the payment thing” Say: “Install the Stripe package with npm and add it as a dependency in package.json”

Instead of: “why is this folder so huge” Say: “Is node_modules in .gitignore? That folder shouldn’t be committed to git.”