What is npm? Package Managers and Why They Exist

You download a project. You open it in Cursor. The AI tells you to run npm install. You type it, hit Enter, and watch as hundreds of packages download. A new folder appears — node_modules — and it contains what appears to be the entire internet. Thousands of folders. Millions of files.

What just happened? Why does a simple app need thousands of packages? And what is npm anyway?

Let's sort this out.

The LEGO Analogy

Imagine you're building a LEGO castle. You could manufacture every brick from scratch — mold the plastic, cut the shapes, paint the colors. But that's absurd. LEGO bricks already exist. You just need the right ones.

Software works the same way. When you're building an app, you need things like:

• A way to handle dates and times
• A way to validate email addresses
• A way to talk to a database
• A way to create beautiful buttons and forms
• A way to handle user authentication

Every developer who has ever lived has needed these same things. So instead of everyone building them from scratch, developers create packages — reusable pieces of code that solve common problems — and share them with the world.

npm (Node Package Manager) is the world's largest collection of these packages. It's the LEGO store for JavaScript and TypeScript developers.

What Is a Package?

A package is a bundle of code that does one specific thing, published for anyone to use. Some examples:

| Package | What It Does | |---------|-------------| | react | Builds user interfaces with reusable components | | next | The framework for building web applications | | stripe | Handles payment processing | | date-fns | Makes working with dates and times easy | | zod | Validates data (ensures emails look like emails, numbers are numbers, etc.) | | tailwindcss | The utility-first CSS framework |

Each package is maintained by someone (a person, a team, or a company), versioned (updated with improvements and bug fixes), and freely available.

What npm Actually Does

npm does three things:

1. Installs Packages

When you run npm install stripe, npm downloads the Stripe package and puts it in your project. Now your code can use Stripe's payment features without you writing payment code from scratch.

2. Manages Dependencies

Packages often depend on other packages. The Stripe package might need a package for making HTTP requests, which needs a package for handling encryption, which needs a package for working with binary data. These are dependencies — the chain of packages that each package requires.

npm handles this automatically. When you install one package, it installs everything that package needs too. This is why npm install sometimes downloads hundreds of packages for what seems like a simple app.

3. Runs Scripts

npm can also run commands defined in your project. npm run dev starts the development server. npm run build creates a production build. These scripts are defined in your project's package.json file.

The package.json File

Every JavaScript/TypeScript project has a package.json file at its root. This is the project's manifest — its identity card. It tells npm:

What the project is called:

{
  "name": "my-awesome-app",
  "version": "1.0.0"
}

What packages it needs:

{
  "dependencies": {
    "next": "^16.0.0",
    "react": "^19.0.0",
    "stripe": "^14.0.0"
  }
}

What commands are available:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

When someone else (or you on a different computer) downloads your project, they run npm install, and npm reads package.json to know exactly which packages to download. This way, the massive node_modules folder doesn't need to be shared — it can be regenerated from the package.json recipe.

The node_modules Folder

This is the folder that contains all the actual package code. When you run npm install, this is what gets created.

Two important things about node_modules:

It's huge. Even a simple project might have a node_modules folder with hundreds of megabytes. This is normal. Don't worry about it.

It's disposable. You never edit anything in node_modules. You never commit it to Git. If you delete it, you can regenerate it by running npm install again. It's like a cache — the package.json is the recipe, and node_modules is the prepared ingredients.

The .gitignore file in your project tells Git to ignore node_modules so it doesn't get uploaded to GitHub. This is already configured in any properly set up project.

npm vs. pnpm vs. yarn

You might encounter these alternative package managers:

npm — The original. Comes installed with Node.js. The default and most widely used.

pnpm — A faster, more efficient alternative to npm. Uses less disk space by sharing packages between projects. Growing in popularity. If you see a pnpm-lock.yaml file in a project, it uses pnpm.

yarn — Created by Meta (then Facebook) as a faster alternative to npm. Popular but less dominant than it used to be. If you see a yarn.lock file, it uses yarn.

They all do the same thing — install and manage packages. The commands are slightly different (pnpm install vs npm install vs yarn install) but the concepts are identical. Use whichever one your project is set up with. If you're starting fresh, npm or pnpm are both great choices.

Common npm Commands for Vibe Coders

Here are the commands you'll use most often:

# Install all packages listed in package.json
npm install
 
# Add a new package to your project
npm install package-name
 
# Start the development server
npm run dev
 
# Build for production
npm run build
 
# Start the production server
npm start

That covers 95% of your npm interactions. If you're using pnpm, just replace npm with pnpm in each command.

When Things Go Wrong

Package-related issues are among the most common problems in web development. Here are the typical scenarios and how to handle them:

"Module not found" error: You're trying to use a package that isn't installed. Run npm install package-name to add it.

"Cannot find module" after cloning a project: You need to run npm install first. The packages aren't included in the repository — you need to download them.

Weird errors after updating a package: Sometimes new versions of packages break things. The package-lock.json file (or pnpm-lock.yaml) records the exact versions that work, so everyone gets the same versions.

The nuclear option: If nothing makes sense and packages seem corrupted, delete the node_modules folder and the lock file, then run npm install again. This reinstalls everything fresh. It's the "turn it off and on again" of the JavaScript world.

Why This Matters for Vibe Coders

Understanding npm helps you in practical ways:

When the AI says "install this package", you know what it means and why.

When something breaks after a package update, you understand the concept of dependencies and can explain the problem to the AI.

When you're choosing between packages (the AI might suggest options), you can look up packages on npmjs.com to see their popularity, maintenance status, and documentation.

When you share your project, you know that package.json is the important file, not node_modules.

Try this now

• Open package.json in a real project and read the dependencies and scripts sections.
• Run the package manager command the repo expects, such as npm install or pnpm install, and notice which lockfile already exists.
• Pick one dependency you do not recognize and look up what job it does before you ask an agent to add another package.
• Confirm that node_modules is ignored by Git and treated as generated output.

Prompt to give your agent

"Help me make a safe package-manager decision for this project.

1. Tell me which package manager this repo is already using and how you know
2. Explain whether I need a new dependency or can use what is already installed
3. If a new package is justified, tell me the tradeoffs and maintenance risk
4. List the exact install and verification steps
5. Stop before switching package managers or adding a dependency just for convenience

Optimize for fewer dependencies, predictable installs, and easy rollback."

What you must review yourself

• Whether the repository already uses npm, pnpm, or yarn and should stay consistent
• Whether the new package actually solves a problem you have instead of just sounding convenient
• Whether the lockfile changed in the way you expected after installation
• Whether the agent is treating node_modules as source code instead of generated output

Common mistakes to avoid

• Adding packages casually. Every dependency adds maintenance, upgrade, and security surface area.
• Ignoring the existing package manager. Mixing npm, pnpm, and yarn creates confusing installs and noisy diffs.
• Committing node_modules. The manifest and lockfile are the source of truth, not the generated folder.
• Running scripts without reading them. npm run something can do anything the script author defined, so inspect unfamiliar commands first.

Key takeaways

• npm and similar tools manage your project's reusable building blocks and the commands around them
• package.json and the lockfile describe the dependency contract; node_modules is generated output
• Agent help is useful here, but dependency choices still deserve human judgment because they affect security, stability, and future maintenance

What's Next

Congratulations — you've now toured the essential tools of modern software development! You understand Git (version control), GitHub (code hosting), the terminal (command line), VS Code/Cursor (your editor), and npm (package management).

In the final module, we'll shift from understanding tools to thinking about products. The MVP Mindset module will teach you how to think about what to build, how to validate ideas, how to choose your tech stack, and how to ship your first product in a week.