npm: packages and scripts

Node.js runs JavaScript; npm is a package manager and CLI; the npm registry hosts packages. A project describes its dependencies and scripts in package.json. Dependencies are local to a project under node_modules unless you deliberately install a tool globally.

A small package

A minimal manifest declares a start script and separates runtime from development dependencies:

{
  "name": "folder-tool",
  "version": "1.0.0",
  "scripts": { "start": "node index.js" },
  "dependencies": {},
  "devDependencies": {}
}

Run scripts with npm run start (or npm start). Install an application dependency with npm install <package>, or a development-only tool with npm install -D <package>. A built-in Node module such as node:fs needs no npm installation. A common convention is a test script that runs a test runner such as Jest; native or very old packages may not work on current Node versions, so prefer maintained ones.

Reproducibility and versions

npm install resolves dependencies and writes package-lock.json; commit the lockfile for applications so collaborators can reproduce resolved versions. npm ci installs from an existing lockfile in a clean environment and errors if it disagrees with package.json. Do not edit node_modules or commit it.

Version entry	Meaning (within the same major)
"1.2.3"	Exactly this version
"~1.2.3"	Compatible patch versions
"^1.2.3"	Compatible minor and patch versions (for stable 1.x)

For 0.x packages, caret behavior is narrower; inspect the resolved version and lockfile rather than assuming ^ always accepts any minor release. Choose maintained packages, read their usage/docs, and investigate audit warnings rather than blindly changing version or security settings.

Try it

Read the package.json example above: find the scripts, identify runtime versus dev dependencies, and predict what npm run start would execute. For a new scratch project, use npm init to create a manifest and compare the result with the example.

npm documentation (opens new window) · Node's npm introduction (opens new window)