TechLearn Hub

Learn Technology in Simple English

What Is npm?

npm is a package manager commonly used with JavaScript and Node.js projects. It helps developers discover, install, update, remove, and manage software packages that their projects depend on.

npm also provides tools for running project scripts, managing dependencies, creating packages, and publishing packages to the npm registry.

Simple meaning: npm makes it easier to use other developers' JavaScript code in your own projects instead of building every feature from scratch.

What Does npm Stand For?

npm is historically associated with the phrase "Node Package Manager." Today, npm is commonly used as the name of the package manager, registry, and ecosystem surrounding JavaScript packages.

When developers say "install it with npm," they normally mean using the npm command-line interface to download and manage a package.

Why Do Developers Use npm?

Modern applications can contain thousands of pieces of reusable code. Instead of creating everything from zero, developers can use packages created and maintained by other developers.

For example, a project may need packages for:

  • Web servers
  • React applications
  • Database access
  • Authentication
  • API requests
  • Testing
  • Build tools
  • CSS processing
  • Command-line applications
  • Development utilities

npm and Node.js

npm is closely connected with the Node.js ecosystem. Installing Node.js using the official installer normally installs npm as well.

Check both installations from your terminal:

node -v
npm -v

If both commands display version numbers, the commands are available in your terminal. If a command is not recognized, check your installation and PATH configuration.

Download Node.js from the official Node.js website.

How to Create an npm Project

A common first step is creating a project directory and initializing it with npm.

mkdir my-project
cd my-project
npm init

npm asks several questions and then creates a package.json file.

You can also use:

npm init -y

The -y option accepts the default answers and quickly creates a basic package.json file.

What Is package.json?

The package.json file contains important information about a JavaScript or Node.js project. It can describe the project, its dependencies, its scripts, and its package metadata.

A simple example looks like this:

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "My first npm project",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  }
}

This example defines a project name, version, description, entry-point field, and start script. The main field is mainly relevant when a package is imported by another project; it does not automatically run the application.

Installing a Package

The main command for installing a package is:

npm install package-name

For example:

npm install express

npm installs Express and its required dependencies into the project's node_modules directory. It also updates dependency information in package.json and the lockfile when applicable.

Learn more in the official npm install documentation.

Installing a Specific Version

You can install a particular package version by adding the version number.

npm install express@5

This requests a version matching the major version 5 range. To request a specific version, use an exact version number:

npm install package-name@1.2.3

Check a package's documentation and compatibility before choosing a version.

Installing Development Dependencies

Some packages are needed only while developing, testing, or building an application. These can be installed as development dependencies.

npm install --save-dev eslint

Development dependencies are normally stored under devDependencies in package.json.

Examples include linters, testing frameworks, and build tools.

What Is node_modules?

The node_modules folder contains packages installed for a project.

For example, after installing Express, a project may look like this:

my-project/
├── node_modules/
├── package.json
├── package-lock.json
└── index.js

The node_modules folder can become large because packages may depend on other packages.

Developers generally avoid committing node_modules to Git. Instead, they share package.json and the lockfile so dependencies can be installed again.

What Is package-lock.json?

npm can create a package-lock.json file that records the resolved dependency tree and package versions. It helps reproduce installations across different environments.

Important: In most application projects, keep package-lock.json in version control alongside package.json.

Avoid manually editing the lockfile unless you understand the changes. Normally, let npm update it when you install or update dependencies.

Installing All Project Dependencies

If a project already contains package.json, open a terminal in the project directory and run:

npm install

npm reads the dependency information and installs the required packages. If a suitable package-lock.json is present, npm uses it to help resolve the installation.

Removing a Package

To remove a package from your project, use:

npm uninstall package-name

For example:

npm uninstall express

This removes the package from the installed dependencies and updates the relevant project configuration.

Updating Packages

npm provides commands for checking and updating packages.

npm outdated
npm update

The first command lists outdated dependencies. The second updates packages according to the version ranges declared in the project.

An update does not necessarily install every newer major version. Read release notes before making major dependency changes.

Running npm Scripts

The scripts section of package.json allows developers to define useful commands.

{
  "scripts": {
    "start": "node index.js",
    "test": "node test.js"
  }
}

Run the scripts with:

npm start
npm test

For other named scripts, use npm run followed by the script name. For example:

npm run build

The command will work only if a corresponding build script is defined.

Example Node.js Project

Suppose you want to create a small Node.js application.

mkdir hello-node
cd hello-node
npm init -y

Create a file named index.js with this code:

console.log("Hello from Node.js!");

Then run:

node index.js

The terminal should display:

Hello from Node.js!

You can later add npm packages when your project needs additional functionality.

Using an npm Package: Express Example

Express is a popular package for creating web servers with Node.js. First, create a project and install Express:

mkdir express-demo
cd express-demo
npm init -y
npm install express

For the following example, add "type": "module" to the top level of package.json. A minimal package.json can look like this:

{
  "name": "express-demo",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node index.js"
  }
}

Create index.js:

import express from "express";

const app = express();

app.get("/", (req, res) => {
  res.send("Hello World!");
});

app.listen(3000, () => {
  console.log("Server running at http://localhost:3000");
});

Start the server:

npm start

Open http://localhost:3000 in a browser on the same machine to test the example.

This example requires Node.js and a terminal. It will not run by simply pasting it into an ordinary HTML page.

npm Registry

The npm registry is an online collection of JavaScript packages. Developers can search for packages, read their documentation, inspect versions, install packages, and publish their own packages.

The npm CLI uses the public npm registry by default, although it can also be configured to use other compatible registries.

Explore packages on the npm website.

Searching for Packages

You can search for packages from the terminal:

npm search express

To inspect packages installed in your project, run:

npm ls

To display only top-level packages, use:

npm ls --depth=0

Before installing an unfamiliar package, check its documentation, maintenance status, version history, and whether it meets your needs.

npm install vs npm ci

Command Common purpose
npm install Install dependencies and update the lockfile when necessary.
npm ci Perform a clean installation based on the existing lockfile.

The npm ci command is useful in automated builds and continuous integration. It requires a lockfile and fails if the lockfile and package.json are not compatible. It also removes an existing node_modules folder before installing.

Global npm Packages

npm can install certain command-line tools globally:

npm install -g package-name

A global installation can make a tool available outside a single project. However, global installation is not necessary for every package. For many tools, you can use npx or a project-local script.

Read the package's official instructions before installing command-line tools.

What Is npx?

npx is a command-line tool associated with npm that can run package commands without requiring you to permanently install every tool globally.

For example, you can start a Vite project with:

npm create vite@latest

Follow the prompts to select the project framework and options. The command may download packages, so you should review what you run.

npm Workspaces

npm supports workspaces, which help manage multiple related packages inside a single repository.

A workspace project might look like this:

company-project/
├── package.json
├── apps/
│   ├── website/
│   └── mobile/
└── packages/
    └── shared/

Workspaces are useful when applications share code or need to be developed together. The root package.json must be configured for the workspaces.

npm Security

npm includes security-related commands such as:

npm audit

This command checks installed dependencies against known security advisories available to npm. It can identify reported vulnerabilities, but it does not guarantee that a project is completely secure.

You can also review available fixes with:

npm audit fix
Be careful: Review the proposed changes and test your application after applying fixes. Do not blindly force major dependency upgrades. Only install packages from sources you trust, and never publish passwords, API keys, or other private credentials.

Publishing an npm Package

Developers can publish reusable JavaScript packages to the npm registry. Before publishing, create an npm account and review the package contents to make sure you are not exposing secrets or private files.

A typical workflow includes:

  1. Prepare package.json and the package files.
  2. Test the package locally.
  3. Sign in to npm from the CLI.
  4. Choose the appropriate package name and version.
  5. Publish when you are ready.

Common commands include:

npm login
npm pack
npm publish

Publishing requires appropriate account permissions and a valid package configuration. Scoped packages may have additional visibility settings.

Read the official npm publishing guide before publishing.

Useful npm Commands

Command Purpose
npm init Create a package.json file.
npm install Install project dependencies.
npm install package Install a package.
npm uninstall package Remove a package.
npm update Update dependencies within their declared ranges.
npm outdated Check outdated packages.
npm run List or run package scripts.
npm start Run the start script, if defined.
npm test Run the test script, if defined.
npm search Search the package registry.
npm ls List installed packages.
npm audit Check for known dependency vulnerabilities.
npm ci Clean-install dependencies from the lockfile.
npm publish Publish a package.

npm vs Yarn

npm and Yarn are package-management tools used in the JavaScript ecosystem. Both can install dependencies, manage project packages, and run scripts.

npm is convenient because it is normally installed with Node.js. Yarn is an alternative with its own commands and configuration. Choose the tool that fits your project and follow one consistent package-management workflow.

npm vs pnpm

pnpm is another JavaScript package manager. It uses a different approach to storing and linking dependencies, which can reduce repeated storage across projects.

npm and pnpm can both manage project dependencies. Their lockfiles and configuration are different, so avoid switching tools in a project without understanding the effects.

npm vs Bun

npm is primarily a package manager and command-line tool in the Node.js ecosystem. Bun is a JavaScript runtime and toolkit that also includes a package manager, test runner, and bundler.

Both support JavaScript development, but they provide different tools and workflows.

npm vs Deno

Deno is a JavaScript and TypeScript runtime with integrated development tools. Modern Deno projects can also use npm packages.

npm remains widely used for managing dependencies in Node.js projects. The best choice depends on the application and the runtime you plan to use.

Common npm Errors and Troubleshooting

1. Command not found

If the terminal cannot find node or npm, verify that Node.js is installed and that its installation directory is available through your PATH. Restart the terminal after installation if necessary.

2. EACCES or permission errors

These errors can occur when npm cannot write to a directory. Check directory permissions and use the recommended setup for your operating system. Avoid using administrator privileges for every npm command.

3. Package not found

Check the package name, registry configuration, and internet connection. A package may be private, unpublished, or unavailable from your configured registry.

4. Dependency conflicts

Review the error output to identify incompatible package versions. Check the packages' supported versions before changing dependencies.

5. Installation fails

Read the complete error message first. Verify your Node.js version, internet connection, disk space, and package configuration. Do not delete the lockfile as the first troubleshooting step.

6. Application does not start

Check that you are in the correct project folder, that the entry-point file exists, and that the required script is defined in package.json.

Recommended Beginner Workflow

  1. Install Node.js from the official website.
  2. Check Node.js and npm versions.
  3. Create a project folder.
  4. Run npm init -y.
  5. Install only the packages you need.
  6. Write your application code.
  7. Add useful scripts to package.json.
  8. Run and test the application.
  9. Keep package.json and package-lock.json together.
  10. Review dependency updates and security warnings carefully.

Simple npm Project Structure

my-app/
├── node_modules/
├── package.json
├── package-lock.json
├── index.js
├── README.md
└── .gitignore

A real project can contain many additional files and folders depending on the framework and application. The .gitignore file commonly includes node_modules/ so installed dependencies are not committed to Git.

Practical Exercises for Beginners

Try these exercises to practice what you have learned:

  1. Check your installed Node.js and npm versions.
  2. Create a folder called practice-npm.
  3. Initialize the project using npm init -y.
  4. Install a small package and inspect package.json.
  5. Run npm ls --depth=0 to list top-level packages.
  6. Create a start script and run it using npm start.
  7. Uninstall the package and inspect the changes.
The exercises require a terminal with Node.js and npm installed. If you only have a mobile HTML editor, you may need a suitable Node.js environment to execute these commands.

Frequently Asked Questions

Is npm a programming language?

No. npm is a package manager and command-line tool used mainly in the JavaScript and Node.js ecosystem.

Do I need Node.js to use npm?

The standard npm CLI runs with Node.js. Installing Node.js using its official installer normally includes npm.

What is npm install?

It installs packages and their dependencies. When run in a project that has package.json, it normally installs the project's declared dependencies.

What is package.json?

It is a project configuration file that can describe the project, dependencies, scripts, and other package information.

What is node_modules?

It is the directory where npm normally places locally installed packages and their dependencies.

What is package-lock.json?

It records the resolved dependency tree to help reproduce installations consistently across environments.

Can I create my own npm package?

Yes. Developers can create reusable JavaScript packages and publish them to the npm registry when they meet the publishing requirements.

Is npm free?

npm provides access to a public registry of packages and free package-management features. Some npm products and services also have paid plans.

Conclusion

npm is an important part of modern JavaScript development. It helps developers install and manage packages, control dependencies, run project scripts, create reusable packages, and work with the wider JavaScript ecosystem.

If you are learning Node.js, React, Express, Vite, or other JavaScript technologies, understanding npm will make your development workflow easier.

Next step: Learn how package.json, dependencies, node_modules, and npm scripts work together in a real project.