What Is npm? Package Management for Vibe Coders

Why AI Coders Need to Know This

Here is the situation: you ask Claude or Cursor to build you a React app. Within seconds, it generates a dozen files and tells you to run a few commands in your terminal. One of them is npm install. You run it. Your terminal fills up with scrolling text. A folder called node_modules appears. It contains 40,000 files and takes up 300 megabytes. You have no idea what just happened.

This is one of the most common "wait, what?" moments for vibe coders. You asked for a web app, not a folder with tens of thousands of files. But npm is not misbehaving — it is doing exactly what it was designed to do, and understanding why is essential for working with any modern JavaScript or TypeScript project.

If you skip learning npm, you will eventually hit walls like:

• A package the AI installed breaks another package — and you do not know how to investigate
• You try to deploy to Vercel or Railway and the build fails with a cryptic npm error
• You accidentally commit node_modules to Git and create a 300MB repository nobody can clone cleanly
• AI installs a package that is abandoned, deprecated, or has a known security vulnerability

npm is not glamorous. It does not make your site look better. But it is the foundation that every JavaScript project runs on, and every AI tool for web development assumes you understand it or will learn it fast. This guide gets you there without the jargon spiral.

Real Scenario

You open Cursor and type something like this:

Build me a simple React app that shows a list of my tasks.
- Use functional components and hooks
- Style it with Tailwind CSS
- Include a form to add new tasks
- Tell me exactly what commands to run to get it working locally

The AI scaffolds the project and responds with something like this:

# First, make sure you have Node.js installed
node --version

# Create a new React project using Vite
npm create vite@latest my-task-app -- --template react

# Move into the project folder
cd my-task-app

# Install all dependencies
npm install

# Install Tailwind CSS
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

# Start the development server
npm run dev

That is four different npm commands, a npx command, a -D flag, and about six concepts happening at once. If you have never used npm before, every line is a potential point of confusion. Let us break it down.

What AI Generated

After running those commands, your project folder looks something like this. This is the structure npm creates when you set up a Vite-based React project:

my-task-app/
├── node_modules/           # ← all installed packages live here (do NOT edit or commit this)
│   ├── react/              # the React library itself
│   ├── react-dom/          # React's browser rendering layer
│   ├── vite/               # the development server and build tool
│   └── (38,000+ more files)
│
├── src/                    # your actual application code
│   ├── App.jsx             # the root component AI wrote
│   ├── App.css
│   └── main.jsx            # entry point that attaches React to the DOM
│
├── public/                 # static files served as-is (favicon, images)
│
├── package.json            # ← the manifest: what packages your project needs
├── package-lock.json       # ← the lockfile: exact versions of everything installed
├── tailwind.config.js      # Tailwind configuration
├── postcss.config.js       # PostCSS configuration (Tailwind needs this)
├── vite.config.js          # Vite bundler configuration
└── index.html              # the HTML shell — React injects itself here

The two files that matter most for understanding npm are package.json and package-lock.json. Everything else is output of those files or your own application code.

Understanding Each Part

What npm actually is

npm is a command-line tool that ships with Node.js. Its job is to manage packages — pre-written JavaScript code libraries that other developers have published so you do not have to write everything from scratch. Instead of writing your own date formatting logic, routing system, or UI component library, you install a package someone else built and tested.

When you install Node.js, npm comes with it. You can verify both are installed by running:

node --version   # e.g. v20.11.0
npm --version    # e.g. 10.2.4

The npm registry at npmjs.com hosts over 2.5 million packages as of 2026. When you run npm install react, npm looks up React in that registry, downloads the files, and puts them in your project.

package.json — the manifest

Every npm project has a package.json file. Think of it as your project's recipe card. It records:

• The name and version of your project
• Which packages your app depends on to run
• Which packages are only needed during development
• Scripts you can run with npm run

Here is what a typical package.json looks like for a Vite + React + Tailwind project:

{
  "name": "my-task-app",
  "version": "0.1.0",
  "private": true,           // prevents accidentally publishing to npm registry

  "scripts": {
    "dev": "vite",           // npm run dev → starts the development server
    "build": "vite build",   // npm run build → compiles your app for production
    "preview": "vite preview" // npm run preview → previews the production build locally
  },

  "dependencies": {          // packages needed for the app to run in production
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },

  "devDependencies": {       // packages only needed during development
    "@vitejs/plugin-react": "^4.3.0",
    "autoprefixer": "^10.4.0",
    "postcss": "^8.4.0",
    "tailwindcss": "^3.4.0",
    "vite": "^6.0.0"
  }
}

The caret (^) before version numbers is a version range. "react": "^19.0.0" means "install React 19.anything, but not React 20." This gives npm some flexibility when resolving package versions, which matters when multiple packages need different versions of shared dependencies.

node_modules — where packages live

node_modules is the folder npm creates when you run npm install. It contains the actual source code for every package your project uses — both the ones you installed directly and all of their dependencies. React depends on other packages. Those packages depend on others. The result is a deep tree of nested code that can easily contain tens of thousands of files.

Three rules for node_modules:

• Never commit it to Git. Add node_modules to your .gitignore file immediately.
• Never edit files inside it. Your changes will be overwritten the next time someone runs npm install.
• You can always delete it and rebuild it. Running npm install recreates node_modules from package.json and package-lock.json.

package-lock.json — the exact recipe

package-lock.json is automatically generated and updated by npm. It records the precise version of every installed package — including all sub-dependencies — so that anyone else who clones your project and runs npm install gets exactly the same code you have. Without a lockfile, version ranges in package.json could resolve to different versions on different machines, causing mysterious "works on my machine" bugs.

Never edit package-lock.json manually. Always commit it to Git alongside package.json.

npm install vs npm run

These two commands do completely different things. Confusing them is one of the most common vibe coder mistakes.

dependencies vs devDependencies

Not every package your project uses needs to ship to production. dependencies are packages your running app needs — React, Express, Axios. devDependencies are tools only used during development — TypeScript compiler, ESLint, Prettier, testing frameworks. When you deploy to production, platforms like Vercel and Railway skip devDependencies by default, keeping the production bundle lean.

To install as a devDependency, use the --save-dev or -D flag:

npm install --save-dev typescript   # added to devDependencies
npm install -D eslint               # shorthand, same result
npm install react                   # no flag = added to dependencies

npx — run without installing

You will often see AI use npx instead of npm. npx downloads and runs a package temporarily without permanently installing it. It is used for one-time scaffolding commands like npx create-react-app or npx tailwindcss init. After it finishes, the package is not kept in your project.

What AI Gets Wrong About npm

AI assistants are generally pretty good at npm commands, but they make a consistent set of mistakes. Knowing these in advance saves real debugging time.

Installing abandoned or deprecated packages

AI training data includes older code. It may recommend packages that were popular in 2020 but are now unmaintained, deprecated, or replaced by better alternatives. For example, AI might suggest moment for date handling when the JavaScript ecosystem has largely moved to date-fns or native Intl. Always do a quick check on npmjs.com — look at the weekly downloads and the last publish date.

Version conflicts it does not notice

Some packages require specific versions of peer dependencies. If AI installs two packages with conflicting requirements, npm may warn you with "peer dependency" messages, or in worst cases, install multiple versions of the same library. AI often ignores these warnings entirely in its generated output. Watch for warnings that include words like WARN, peer, or unmet in the install output.

Mixing npm and yarn or pnpm commands

There are three popular JavaScript package managers: npm, Yarn, and pnpm. They are not interchangeable. AI sometimes mixes commands from different managers — writing yarn add in one line and npm install in another. If you see yarn.lock or pnpm-lock.yaml in a project, it is using a different package manager. Pick one per project and stick to it.

Forgetting to add packages to package.json

AI sometimes writes code that imports a package without also installing it. If your app crashes with Cannot find module 'some-package', that package is missing from node_modules. Run npm install some-package to fix it. A clean way to check: everything your code imports should appear in dependencies or devDependencies in package.json.

Telling you to run npm install --force to fix conflicts

npm install --force overrides version conflict errors by ignoring them. AI occasionally suggests this as a quick fix. While it can unblock you in the moment, it can also create subtle runtime bugs where incompatible package versions end up in your project. Use it only as a last resort and know that it may hide real problems.

How to Debug npm Problems With AI

npm errors are often intimidating because they print a lot of text. The key skill is learning to find the actual error in the noise — usually a line with ERR! or error near the bottom of the output.

In Cursor

Cursor's terminal panel captures npm output directly. When an install fails, copy the last 20 lines of the error and paste them into the Cursor chat with a prompt like: "npm install failed with this error. What is the root cause and how do I fix it?" Cursor can usually identify whether the issue is a Node.js version mismatch, a peer dependency conflict, or a missing package entirely.

Tip: Ask Cursor to check your Node.js version against the package's engine requirements. Many npm errors are caused by running a package that needs Node 18+ on a machine still running Node 16.

In Windsurf

Windsurf's Cascade agent understands npm project structure well. Open the chat and say: "I ran npm install and got this error. Explain what caused it and give me the correct fix." Paste the full error output — do not paraphrase it. The exact error text is what Windsurf needs to give you a precise answer rather than a generic guess.

If you see peer dependency warnings that are not breaking anything, ask Windsurf: "Are these peer dependency warnings going to cause problems in production, or are they safe to ignore?" That question alone saves a lot of unnecessary debugging spirals.

In Claude Code

Claude Code (the CLI) can read your package.json directly. Try: "Read my package.json and tell me if there are any dependency issues, outdated packages, or missing packages based on the code in my src/ folder." Claude Code can cross-reference your imports against your declared dependencies and spot the mismatch without you having to hunt through every file manually.

Common fixes for common npm errors

What to Learn Next

Once you understand npm, a few closely related concepts start to click:

• What Is Git? — npm and Git work together constantly. You commit package.json and package-lock.json to Git, and you put node_modules in .gitignore. Understanding both makes deployments and collaboration dramatically less painful.
• What Is an Environment Variable? — After npm installs your packages, the next thing AI usually wants you to set up is environment variables. API keys, database URLs, and secret tokens should never go in your code — they go in environment variables.
• What Is React? — React is almost always one of the first packages AI installs via npm. Understanding what React is helps you understand why it needs npm in the first place.
• What Is JavaScript? — npm manages JavaScript packages, so a working understanding of JavaScript itself helps you reason about why certain packages exist and what problem they solve.
• What Is Jest? — Jest is the most popular JavaScript testing framework, installed via npm. AI can write your tests — but you need to know how to run them.
• What Is Vite? — The modern build tool AI uses instead of Create React App. It's an npm package that transforms how your project runs in development.

FAQ