Node.js Part 3: npm and package.json: Installing and Managing Packages

What you should know first: read Node.js Part 1: What Is Node.js and Node.js Part 2: Modules in Node.js. You should know how to run a file with node file.js and how import / export work.

In Part 2 you split your own code into modules. But most code in a real Node.js app is not written by you. Date formatting, web frameworks, database drivers, testing tools: someone has already built them and shared them for free. npm and package.json are how you find, install and manage that shared code. In this part you will learn, step by step, what npm is, what every important line of package.json means, how to install and remove packages, what the strange ^ and ~ symbols in version numbers mean, why package-lock.json exists, and how to run your project with npm scripts.

What is npm?

npm (short for Node Package Manager) is installed automatically with Node.js. The word “npm” is used for three connected things:

A package is simply a folder of code with its own package.json. When you install one, you can import it exactly like the modules you wrote in Part 2. Check that npm is ready:

# npm comes with Node.js, so both commands should print a version
$ node -v
v22.23.4
$ npm -v
10.9.9

Your numbers may be higher, and that is fine. Everything in this tutorial works with the npm version that ships with Node.js 22, 24 or 26.

Create a package.json file

Every Node.js project starts with a package.json file in its main folder. You can write it by hand, but the quickest way is npm init. The -y flag answers “yes” to every question and uses default values.

# create a new project folder and a package.json inside it
$ mkdir my-first-npm-app
$ cd my-first-npm-app
$ npm init -y
Wrote to /home/you/my-first-npm-app/package.json:

{
  "name": "my-first-npm-app",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

This is the file npm init -y created. Hover a line to highlight it.

Two quick improvements you will want in almost every new project: switch to ES modules and add a description. You can edit the file in your editor or use the npm pkg command, which edits package.json safely for you:

$ npm pkg set type=module
$ npm pkg set description="My first app with npm packages"
$ npm pkg get type
"module"

package.json fields explained

You do not need to memorise every field. These are the ones you will use every week. Click the tabs to explore them:

The full list of fields is in the official npm package.json documentation.

Installing your first npm package

Let us install dayjs, a tiny and popular library for working with dates. Run this inside your project folder:

$ npm install dayjs

added 1 package, and audited 2 packages in 459ms

found 0 vulnerabilities

Now use the package. Because dayjs lives in node_modules, you import it by its package name, with no ./ and no file extension. That is how Node.js knows to look in node_modules instead of your own files.

// app.js – use an npm package like any other module
import dayjs from "dayjs";

const launch = dayjs("2026-12-25");
const today = dayjs("2026-11-06");

console.log("Launch date:", launch.format("DD MMM YYYY"));
console.log("Days to go:", launch.diff(today, "day"));
console.log("One week later:", today.add(7, "day").format("dddd, D MMMM"));

$ node app.js
Launch date: 25 Dec 2026
Days to go: 49
One week later: Friday, 13 November

Click ▶ Run to see the real output.

dependencies vs devDependencies

Some packages are part of your running app. Others only help you while you write code. npm keeps them in two separate lists:

For this tutorial we install semver (the same version-checking library that npm itself uses) as a dev dependency, because we only need it to experiment:

$ npm install -D semver
added 1 package, and audited 3 packages in 402ms

found 0 vulnerabilities

Version numbers and ranges (^ and ~)

Look at package.json after installing and you will see "dayjs": "^1.11.23". That little ^ is a version range. npm packages use semantic versioning (semver): MAJOR.MINOR.PATCH.

Seeing is believing. This small script uses the semver package to check which versions each range accepts:

// versions.js – see which versions a range accepts
import semver from "semver";

const ranges = ["^1.11.0", "~1.11.0", "1.11.0", ">=1.10.0 <2.0.0"];
const versions = ["1.11.0", "1.11.23", "1.12.0", "2.0.0"];

for (const range of ranges) {
  const ok = versions.filter((v) => semver.satisfies(v, range));
  console.log(range.padEnd(16), "->", ok.join(", "));
}

$ npm run versions
> my-first-npm-app@1.0.0 versions
> node versions.js

^1.11.0          -> 1.11.0, 1.11.23, 1.12.0
~1.11.0          -> 1.11.0, 1.11.23
1.11.0           -> 1.11.0
>=1.10.0 <2.0.0  -> 1.11.0, 1.11.23, 1.12.0

Click ▶ Run to see which versions every range allows (real output).

package-lock.json and npm ci

If package.json says ^1.11.23, then today you may get 1.11.23 and next month your teammate may get 1.12.0. To avoid “it works on my machine” bugs, npm writes package-lock.json: the exact version, download URL and integrity hash of every installed package, including the packages that your packages depend on.

{
  "name": "my-first-npm-app",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "node_modules/dayjs": {
      "version": "1.11.23",
      "resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.23.tgz",
      "integrity": "sha512-QDTCU0M0MxR3hQfnlDJfwekQiaanm1ubOD231u73WBckQ/...",
      "license": "MIT"
    },
    "node_modules/semver": {
      "version": "7.8.6",
      "dev": true,
      "license": "ISC"
    }
  }
}

A shortened view of the real lock file. The integrity hash is cut for space.

• Always commit package-lock.json to Git. Never edit it by hand.
• npm install may update the lock file when package.json changes.
• npm ci (“clean install”) deletes node_modules and installs exactly what the lock file says. It fails if the two files do not match. Use it in CI pipelines and on servers. Our GitHub Actions CI/CD for Node.js guide uses it in every workflow.

# fresh, exact install from package-lock.json
$ npm ci
added 2 packages, and audited 3 packages in 475ms

found 0 vulnerabilities
# production server: skip devDependencies
$ npm ci --omit=dev

npm scripts: start, dev and test

Instead of remembering long commands, put them in the "scripts" section of package.json. Here is our finished file with four scripts:

{
  "name": "my-first-npm-app",
  "version": "1.0.0",
  "description": "",
  "scripts": {
    "test": "node --test",
    "start": "node app.js",
    "dev": "node --watch app.js",
    "versions": "node versions.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "module",
  "dependencies": {
    "dayjs": "^1.11.23"
  },
  "devDependencies": {
    "semver": "^7.8.6"
  }
}

$ npm start
> my-first-npm-app@1.0.0 start
> node app.js

Launch date: 25 Dec 2026
Days to go: 49
One week later: Friday, 13 November

Click ▶ Run to run npm start (real output).

• npm start and npm test are special: they work without the word run.
• Every other script needs npm run: npm run dev, npm run versions.
• node --watch app.js restarts your app every time you save a file. It is built into Node.js, so you no longer need nodemon for simple projects.
• Run npm run with no name to list every script in the project.

You can also set scripts from the terminal with npm pkg set:

$ npm pkg set scripts.dev="node --watch app.js"
$ npm run
Lifecycle scripts included in my-first-npm-app@1.0.0:
  test
    node --test
  start
    node app.js
available via `npm run-script`:
  dev
    node --watch app.js
  versions
    node versions.js

Running tools with npx

npx also comes with npm. It runs a command from a package without installing it globally. If the package is already in your project, npx uses that copy; otherwise it downloads it to a cache and runs it. Here we use the semver command-line tool from our dev dependency:

# which of these versions match ^1.11.0?
$ npx semver -r "^1.11.0" 1.10.7 1.11.5 1.12.0 2.0.0
1.11.5
1.12.0
# create projects without global installs (asks before downloading)
$ npx create-vite@latest my-react-app

Update, remove and audit packages

Packages get new versions all the time. These commands keep your project healthy. Here an older project has dayjs pinned to 1.11.10:

# what is out of date?
$ npm outdated
Package  Current   Wanted   Latest  Location            Depended by
dayjs    1.11.10  1.11.10  1.11.23  node_modules/dayjs  old
# update within your ranges (the "Wanted" column)
$ npm update
# jump to the newest version, even a new major
$ npm install dayjs@latest
# remove a package from node_modules and package.json
$ npm uninstall semver
# check for known security problems
$ npm audit
$ npm audit fix
# see what is installed
$ npm ls

Current is what you have, Wanted is the newest version allowed by your range, and Latest is the newest version on the registry. When Latest is a new major version, read the package changelog before upgrading.

Common errors and fixes

npm and package.json best practices

1. Commit package.json and package-lock.json; ignore node_modules. Anyone can rebuild node_modules with one command.
2. Use npm ci in CI and on servers. It is faster and gives exactly the versions you tested.
3. Put tools in devDependencies. Production stays smaller, faster to install and safer.
4. Check a package before installing it: weekly downloads, last publish date, open issues and licence on npmjs.com. Fewer, well-maintained packages mean fewer security problems.
5. Watch for typos. Attackers publish look-alike names (for example expresss). Copy names from the official docs.
6. Run npm audit and npm outdated regularly, and update in small steps with your tests running.
7. Add "private": true and engines to app projects so nobody publishes them by mistake and everyone knows the Node.js version.

Practice task

Build a tiny “festival countdown” app using npm:

1. Create a folder countdown, run npm init -y and npm pkg set type=module.
2. Install dayjs as a dependency.
3. Create app.js that prints how many days are left until Diwali, New Year and your birthday.
4. Add scripts: start (node app.js) and dev (node --watch app.js).
5. Delete node_modules, run npm ci, then npm start. It should still work, because the lock file remembers everything.
6. Bonus: install semver as a dev dependency and use npx semver to test which versions ~1.11.0 accepts.

FAQ

Conclusion

You now know how npm and package.json work together. npm downloads packages from the registry into node_modules; package.json lists what your project needs and the scripts it runs; package-lock.json remembers the exact versions. You can tell dependencies from devDependencies, read version ranges like ^ and ~, use npm ci for reliable installs, run tools with npx and keep packages updated and safe. These skills are used in every Node.js project you will build in the rest of this series.