npm and Packages: package.json, Installing Dependencies and npm Scripts

npm (Node Package Manager) installs and manages packages: reusable code published by other developers, from small utilities to whole frameworks such as React and Express. It comes with Node.js, and the npm registry is the largest collection of open-source packages for any language.

Starting a project#

In a new, empty folder:

npm init -y

This creates package.json, the file that describes your project:

{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {},
  "devDependencies": {}
}

(npm init -y writes a few more default fields; "type": "module" was added by hand so import works in .js files, as explained in Modules.)

Installing packages#

npm install date-fns

This:

1. downloads the package (and the packages it depends on) into node_modules/;
2. adds it to dependencies in package.json;
3. records the exact installed versions in package-lock.json.

Then import it by name:

import { format, addDays } from "date-fns";

console.log(format(addDays(new Date(2026, 9, 24), 7), "d MMMM yyyy"));   // 31 October 2026

dependencies and devDependencies#

Removing and updating#

npm uninstall date-fns
npm outdated
npm update

npm outdated lists packages with newer versions; npm update updates them within the allowed version ranges.

Version numbers#

Packages use semantic versioning: MAJOR.MINOR.PATCH, such as 4.1.0.

In package.json, "^4.1.0" means "4.1.0 or any newer 4.x version" (no major updates), and "~4.1.0" means "4.1.x only".

node_modules and the lock file#

• node_modules/ can contain thousands of files. Never edit it and never commit it to Git: add it to .gitignore. Anyone can recreate it with npm install.
• package-lock.json records the exact version of every installed package. Do commit it, so everyone (and your server) installs exactly the same versions.
• npm ci installs exactly what the lock file says, which is what automated builds should use.

npm scripts#

The scripts section defines shortcuts for common commands:

{
  "scripts": {
    "start": "node server.js",
    "dev": "node --watch server.js",
    "test": "node --test",
    "lint": "eslint ."
  }
}

npm run dev
npm test
npm start

npm run <name> runs any script; start and test also have the shortcuts npm start and npm test. Scripts can use tools installed in node_modules directly by name, such as eslint. (node --watch restarts your program when files change, and node --test runs Node's built-in test runner.)

npx: run a package without installing it#

npx prettier --write .
npx create-vite@latest my-site

npx runs a package's command, downloading it temporarily if it is not installed. It is commonly used for project generators such as create-vite.

Global installs#

npm install -g name installs a command for your whole computer. Prefer local (per-project) installs with npm scripts or npx, so each project records the exact tool versions it needs.

Using packages safely#

Every package you install is code you run with full access to your project and computer. A few habits:

• Prefer well-known, actively maintained packages. Check the weekly downloads, recent releases and GitHub repository on npmjs.com.
• Do not install a package for something a few lines of code can do.
• Watch for typos in names: attackers publish look-alike packages.
• Run npm audit to check for known vulnerabilities, and keep dependencies updated.

Other package managers#

pnpm, Yarn and Bun use the same npm registry and package.json, with differences in speed and disk usage. If a project has a pnpm-lock.yaml or yarn.lock, use that tool for it.

Practice#

{
  "scripts": {
    "start": "node src/index.js",
    "dev": "node --watch src/index.js",
    "format": "prettier --write ."
  },
  "devDependencies": {
    "prettier": "^3.0.0"
  }
}

Key takeaway#