Glossary

npm

npm manages JavaScript dependencies and project scripts. It is not the Node.js runtime or the same thing as the public npm registry; they are connected but distinct layers.

Short definition

Dependencies are declared, locked, and installed deliberately.

The npm CLI reads package.json, where a project describes its own name, scripts, and acceptable versions of direct dependencies. During installation, it resolves indirect dependencies too, stores them in node_modules, and usually creates or updates package-lock.json. The lockfile records a concrete tree from which the same environment can be built again.

Node.js is the runtime that runs a program. npm is a package manager and project tool. The public npm registry is a service containing published packages; npm can also work with a private registry, a Git repository, a tarball, or a local path. npm must therefore not be equated with either Node.js or a registry itself.

The name npm is commonly pronounced en-pee-em. In documentation and conversation it can refer to the CLI, public ecosystem, or the company around the registry, but in technical design it is clearer to distinguish the npm command, lockfile, registry, and a specific package. In a frontend project, npm typically runs TypeScript, Playwright, and a build; PHP dependencies have the analogous but separate role of Composer.

What it is used for

From one library to a reproducible build in CI

npm connects a project declaration, package sources, and common team commands. A successful installation alone does not prove that an application behaves correctly.

adding and updating libraries for a frontend, Node.js service, or development tools
creating and committing package-lock.json for a reproducible application installation
running shared commands such as test, lint, build, or start through the scripts section
separating runtime, development, optional, and peer dependencies by their role
working with public and private registries and scoped packages
a basic check for known vulnerabilities through npm audit as one security layer

Practical example

The project declares intent; the lockfile keeps the exact result

The package.json example says that the application needs the express library at a version matching the stated semver range and that tests run through one shared command. After a controlled dependency change, package-lock.json is reviewed too, because it contains the exact versions of direct and indirect packages.

In CI or when deploying an application, npm ci is usually used with the committed lockfile. The command does not search for a new set of versions or rewrite package.json and package-lock.json. If the files conflict, it fails, which is more useful than silently creating a different build.

JSON

{
  "name": "shop-tools",
  "private": true,
  "scripts": {
    "test": "node --test",
    "build": "node scripts/build.js"
  },
  "dependencies": {
    "express": "^5.0.0"
  },
  "devDependencies": {
    "eslint": "^9.0.0"
  }
}

How it works

From a dependency declaration to the same build

package.json and package-lock.json have different roles. Together they give a team clarity and reproducibility.

package.json The project declares direct dependencies, version ranges, scripts, metadata, and sometimes package-management settings.
Tree resolution npm selects compatible direct and indirect dependencies according to the declaration, lockfile, and project configuration.
package-lock.json It records concrete resolved packages, their sources, and integrity data for the next reproducible installation.
node_modules and scripts Locally installed packages are available to the application, and their command-line tools can be used by scripts in package.json.
CI and deployment A clean install from an approved lockfile, tests, and a build provide confidence that this is the same set that passed checks.

Important distinctions

Managing packages is not running an application or a security review.

Separating the layers helps select the right security and operational step.

Node.js

A runtime for running JavaScript outside the browser. npm is often installed with it, but does not run an application in the same role as a node process.

Registry

A service for publishing and downloading packages. The npm CLI can use the public registry, a private registry, and other package sources.

Package

A distributable unit described by package.json. It can be a library, CLI, or whole application; its presence in a registry is not a security review.

Lockfile

A concrete resolved dependency tree. It is not a replacement for the package.json declaration or a guarantee that package code is correct or safe.

Bundler and framework

npm often installs these tools and invokes them through scripts. npm does not define the resulting frontend bundle or an application architecture.

Important files and commands

Installation, lockfiles, and scripts are not interchangeable.

Choose a command by intent: changing a dependency is different work from cleanly building an already approved project.

package.json

It is the project declaration and the acceptable versions of direct dependencies. A semver range such as ^5.0.0 does not say that exactly one fixed version will always be installed.

package-lock.json

It is the concrete dependency-tree state for an application. It belongs in version control and should not be edited manually. Without a lockfile, a later install may resolve a different set of indirect dependencies.

npm install

Use it to add or deliberately change a dependency. With no arguments it respects the lockfile when it matches package.json; when they conflict it can resolve the tree again and update package-lock.json. It is not a frozen install.

npm ci

Use it for a clean installation of the whole application in CI, tests, or deployment. It requires a lockfile, checks that it matches package.json, removes existing node_modules, and does not write package.json or the lockfile. It cannot add one new package. If the lockfile was created with flags that change the tree shape, npm ci must use the same flags or the project .npmrc.

Scripts and command-line tools

The scripts section standardises team commands through npm run. During installation, package lifecycle hooks can run code; configuration such as ignore-scripts can limit this behaviour, but may also break a legitimate dependency build.

Registries and scopes

A registry is the source of published packages, not a synonym for the npm CLI. A scope such as @company/tool helps separate an internal source and access rules, but does not replace package review or token management.

Benefits and limits

A fast ecosystem at the cost of careful supply-chain management.

Benefits

a reproducible application build thanks to a lockfile
shared scripts for development, tests, linting, and builds
a large choice of libraries and tools for the JavaScript ecosystem
the ability to separate public and private package sources

Risks and mistakes

adding a small package can bring many indirect dependencies and install-time code
npm install and npm ci have different purposes; mixing them up hides changes or breaks a clean build
an uncommitted or inconsistent lockfile creates different environments
automatic npm audit fix can change the dependency tree and is not a substitute for review
globally installed tools hurt reproducibility when a project does not pin their version

When it fits

For every maintained project with JavaScript dependencies.

npm is a natural choice for frontend projects, Node.js services, and tools that need to manage libraries, tests, or a build. In an application, package.json, package-lock.json, and relevant configuration are usually committed together so that a developer, CI, and production build use the same decision.

Do not install a package only because it saves a few lines of code. Consider maintenance activity, licence, supported Node.js versions, the indirect dependency tree, install scripts, and actual project value. A small local function can be clearer and safer without another package.

Security and quality

Installing a package executes a supply-chain change.

Packages, configuration, and lockfiles deserve the same review as your own source code.

commit package.json, package-lock.json, and project configuration that affects the dependency-tree shape
use npm ci with an approved lockfile in CI and deployment instead of a general update
before adding a package, assess its purpose, maintenance activity, licence, tree size, and publication source
review lockfile and install-script changes as carefully as changes to your own code
use npm audit for an overview of known vulnerabilities, but assess findings by reachability and test fixes
do not run npm audit fix or a broad update without review; audit fix uses the installation mechanism and can change the dependency tree
protect registry tokens, limit their permissions, and do not expose them to untrusted builds or install scripts

Frequently asked questions

npm without risky shortcuts

Is npm the same as Node.js?

No. Node.js is the runtime for running JavaScript outside the browser. npm is the package-management and scripts tool. They are often installed together but solve different tasks.

Is npm the same as the npm registry?

No. A registry is a service from which packages are published and downloaded. The npm CLI can communicate with a registry, but it can also work with other registries or sources.

What is the difference between npm install and npm ci?

npm install also serves to change dependencies and can update the lockfile when it is not in sync with package.json. npm ci performs a clean, frozen installation of the whole project from an existing lockfile; it fails on mismatch and does not modify the files.

Should package-lock.json be in Git?

For an application, usually yes. It records the concrete tree that the team, CI, and deployment should repeat. A lockfile change is reviewed together with the package.json change.

Does npm audit prove dependencies are safe?

No. It reports known vulnerabilities using registry information, but does not assess every vulnerability, a malicious package, configuration, or whether a problem is reachable. The result is review input, not a security certificate.

Why can installation scripts be risky?

They can run code in a developer or CI context during installation. You need to know the package source, protect tokens, and understand which scripts and permissions a build truly needs.

How I work with development environments

I treat dependencies as part of safe and reproducible deployment.

For long-lived applications, I connect version control, CI, review, and operational environments so that a package change is traceable and testable.

How I work with APIs and integrations Discuss a project without obligation