Managing Dependencies: npm install and package.json Explained

Previously in this course, we covered Initializing Projects with NPM: The package.json Manifest, where we generated our project’s manifest file. Now that we have a foundation, this lesson adds the ability to expand our project’s capabilities by pulling in third-party code from the vast npm registry.

Package Management from First Principles

In professional development, you rarely write every piece of logic from scratch. Whether you need a web framework like Express or a utility library, you’ll lean on the Node Package Manager (npm).

When you run an install command, npm performs three critical actions:

1. Downloads the code: It fetches the requested package from the registry and places it into a folder named node_modules.
2. Updates the manifest: It records the package name and version in your package.json file.
3. Locks the state: It updates package-lock.json to ensure every developer on your team installs the exact same version of that code.

The Anatomy of npm install

The command npm install (often abbreviated as npm i) is your primary tool. However, it's vital to categorize the packages you install. We divide them into two buckets:

Installing Production Dependencies

When you build a server, it needs specific libraries to handle HTTP requests. To install a package and save it to your dependencies, use the default flag:

Bash
npm install express

Note: In older versions of npm, you had to use --save. Today, npm install saves to your dependencies by default.

Installing Development Dependencies

Some tools are only for you, the developer. For example, nodemon automatically restarts your server when you save a file. You don’t need this running on your production server. Use the --save-dev or -D flag:

Bash
npm install nodemon --save-dev

Worked Example: Building Our Project

We are building a REST API, so let's set up our workspace with the necessary tools. Open your terminal in your project directory and run:

1. Install Express:

   Bash
   npm install express
   

   Check your package.json. You will see a new entry under "dependencies".

2. Install a development tool:

   Bash
   npm install nodemon -D
   

   Check your package.json again. You will see "devDependencies" created with nodemon inside.

3. Verify the node_modules folder: Run ls node_modules (or dir on Windows). You will see a directory full of folders. This is where the physical code for your dependencies lives. Never edit files inside this folder directly.

Hands-on Exercise

1. Open your terminal inside your project folder.
2. Install the dotenv package (used for managing environment variables) as a regular dependency.
3. Install jest (a testing framework) as a development dependency.
4. Open your package.json and confirm that the versions of these packages appear under their respective keys.

Common Pitfalls

• Committing node_modules: Never commit your node_modules folder to Git. It can contain thousands of files and is platform-specific. Always include node_modules in your .gitignore file.
• Misunderstanding package-lock.json: Beginners often delete this file when they run into issues. Don't! This file ensures consistency. If you have trouble with resolution, look into how to debug dependency conflicts instead.
• Global vs Local: Avoid installing packages globally (using the -g flag) unless they are CLI tools. Always prefer local installations to keep your project portable.

FAQ

What happens if I delete node_modules? Don't panic! Since your package.json and package-lock.json are saved, you can simply run npm install in the terminal, and npm will download everything needed to get your project back to its original state.

How do I update my packages? You can run npm update to upgrade packages within the version ranges defined in your package.json.

Why does my node_modules folder look so big? Dependencies often have their own dependencies. npm installs the entire tree of these requirements, which is why the folder grows quickly. This is normal.

Recap

We’ve learned that npm install is the standard way to add external logic to our projects. By distinguishing between dependencies and devDependencies, we keep our production builds lean and our development environment feature-rich. We’ve also reinforced the importance of the manifest file and the node_modules directory as the hub of our application's ecosystem.

Up next: We will dive into modules, learning how to structure our own code and use the require function to glue it all together.