npm and Package Management

Every Node.js project relies on packages — reusable code written by other developers. The tool that manages these packages is called npm (Node Package Manager). Understanding npm is essential because every AI-generated project uses it.

What is npm?

npm is three things:

1. A command-line tool — you run npm install, npm start, etc. in your terminal
2. A registry — a massive online library of over 2 million packages (npmjs.com)
3. A package manager — it handles downloading, updating, and organizing packages

When Claude Code generates a project and says "run npm install," it's telling you to download all the packages the project needs.

package.json Explained

Every Node.js project has a package.json file at its root. Think of it as the ID card for your project. Here's what a typical one looks like:

{
  "name": "my-ai-app",
  "version": "1.0.0",
  "description": "An AI-powered web application",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "dev": "nodemon index.js",
    "build": "tsc",
    "test": "jest"
  },
  "dependencies": {
    "express": "^4.18.2",
    "openai": "^4.20.0",
    "dotenv": "^16.3.1"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "nodemon": "^3.0.0",
    "@types/express": "^4.17.21"
  }
}

Let's break down each section:

dependencies vs devDependencies

This distinction matters:

• dependencies — Your app needs these to work. Examples: Express (web server), OpenAI SDK (AI calls), dotenv (env variables)
• devDependencies — Only needed while developing. Examples: TypeScript compiler, testing tools, linters

Essential npm Commands

Creating a New Project

# Create a new project (interactive — asks you questions)
npm init

# Create a new project with defaults (skip the questions)
npm init -y

This creates a package.json file for you.

Installing Packages

# Install a package as a dependency
npm install express
# Shorthand:
npm i express

# Install multiple packages at once
npm install express dotenv openai

# Install as a devDependency
npm install --save-dev typescript nodemon
# Shorthand:
npm i -D typescript nodemon

# Install ALL packages listed in package.json
npm install
# This is what you run after cloning a project

Uninstalling Packages

# Remove a package
npm uninstall express

# Remove a dev dependency
npm uninstall --save-dev nodemon

What to ask your AI: "What npm packages do I need for a project that [describe your project]?"

Understanding node_modules

When you run npm install, packages get downloaded into a folder called node_modules. This folder can get very large (hundreds of megabytes) because each package may have its own dependencies.

Important rules about node_modules:

1. Never edit files inside node_modules — they'll be overwritten on the next install
2. Never commit node_modules to Git — add it to your .gitignore file
3. You can always recreate it — just run npm install and it downloads everything again

Setting Up .gitignore

Every Node.js project should have a .gitignore file that includes:

# .gitignore
node_modules/
.env
dist/
.DS_Store

This tells Git to ignore these files and folders. You never want to upload node_modules or your secret .env file to GitHub.

package-lock.json

After running npm install, you'll see a package-lock.json file. This file records the exact versions of every package that was installed.

Why it matters:

• package.json says "I need Express version 4.18 or higher" (^4.18.2)
• package-lock.json says "I installed Express version 4.18.2 exactly"

This ensures everyone on your team (and your deployment server) uses the exact same versions.

Rules:

• Do commit package-lock.json to Git
• Don't edit it manually
• Don't delete it (unless you want to regenerate it)

npm Scripts

Scripts are shortcuts defined in your package.json. Instead of typing long commands, you define a short name:

{
  "scripts": {
    "start": "node dist/index.js",
    "dev": "nodemon src/index.ts",
    "build": "tsc",
    "test": "jest",
    "lint": "eslint src/",
    "seed": "ts-node scripts/seed.ts"
  }
}

Run them with npm run:

# Special scripts (don't need "run")
npm start
npm test

# All other scripts need "run"
npm run dev
npm run build
npm run lint
npm run seed

Common scripts you'll see in AI-generated projects:

npx — Run Without Installing

npx lets you run a package without permanently installing it:

# Instead of installing create-next-app globally:
npx create-next-app@latest my-app

# Run a one-off tool:
npx ts-node script.ts

# Run a specific version:
npx prisma@latest init

This is handy for:

• Project scaffolding tools (create-next-app, create-vite)
• One-time scripts
• Trying out packages before installing them

What to ask your AI: "I cloned a project and I see a package.json. Walk me through what each dependency does and how to get started."

Common Beginner Mistakes

What's Next?

You understand npm and how packages work. The next tutorial covers modules and imports — how Node.js files connect to each other and how you use the packages you've installed.

What to ask your AI: "I'm setting up a new Node.js project. What packages should I install for a [REST API / web scraper / AI chatbot]?"

---

🌐 www.genai-mentor.ai