npm and package.json Explained: Installing Node.js Packages

npm (Node Package Manager) comes with Node.js. It installs packages (reusable code published by others) from the npm registry, records which ones your project needs, and runs project scripts. Almost every Node.js project starts with npm.

Create package.json#

package.json describes your project: its name, version, scripts and dependencies. Create one with:

npm init -y

Wrote to C:\Projects\laviyx-course-demo\my-app\package.json:

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

-y accepts the default answers. Most fields are optional; the important ones are name, version, scripts, dependencies and type.

Current npm versions set "type": "commonjs". To use ES modules (import/export), as this course does, change it:

npm pkg set type=module

npm pkg set edits package.json for you; you can also edit the file by hand.

Install a package#

Install dayjs, a small date library:

npm install dayjs

This downloads the package into a node_modules folder, adds it to dependencies in package.json, and records the exact installed version in package-lock.json. Then import it by name:

import dayjs from "dayjs";

const order = dayjs("2026-10-20");
const delivery = order.add(5, "day");
console.log("Ordered:", order.format("DD MMM YYYY"));
console.log("Delivery:", delivery.format("dddd, DD MMM YYYY"));
console.log("Days until delivery from 22 Oct:", delivery.diff(dayjs("2026-10-22"), "day"));

node dates.js

Ordered: 20 Oct 2026
Delivery: Sunday, 25 Oct 2026
Days until delivery from 22 Oct: 3

Package imports have no ./: Node looks for them in node_modules.

dependencies vs devDependencies#

• dependencies: packages your code needs to run (Express, a database driver, dayjs).
• devDependencies: tools only needed during development (test runners, linters, TypeScript), installed with -D:

npm install -D vitest

Other useful commands:

Versions and the lock file#

Versions follow semantic versioning: MAJOR.MINOR.PATCH.

• PATCH (1.11.23): bug fixes;
• MINOR (1.12.0): new features, backwards compatible;
• MAJOR (2.0.0): breaking changes.

When this lesson was written, npm install dayjs installed version 1.11.23 and recorded "dayjs": "^1.11.23" in package.json. The caret means "1.11.23 or any later 1.x version". ~1.11.23 allows only patch updates (1.11.x), and 1.11.23 means exactly that version.

package-lock.json records the exact version of every installed package, including packages your packages depend on, so everyone on the team and every server installs identical code. Commit it to Git. On servers and in CI, npm ci installs exactly what the lock file says.

Scripts#

The scripts field defines commands run with npm run:

{
  "name": "my-app",
  "type": "module",
  "scripts": {
    "start": "node dates.js",
    "dev": "node --watch dates.js",
    "greet": "node -e \"console.log('Hello from an npm script')\""
  },
  "dependencies": {
    "dayjs": "^1.11.23"
  }
}

npm run greet --silent

Hello from an npm script

npm start and npm test are shortcuts for npm run start and npm run test. Scripts can use any tool installed in the project's node_modules/.bin, so "test": "vitest" works without a global install. (--silent hides npm's own header lines.)

npx#

npx runs a package's command without installing it globally, downloading it temporarily if needed. Generators are usually run this way: npx create-next-app@latest, npm create vite@latest (which uses the same mechanism).

node_modules and Git#

node_modules can contain thousands of files and is rebuilt by npm install, so never commit it. A .gitignore for Node projects starts with:

node_modules/
.env

Choosing packages#

Before installing a package, check its weekly downloads, recent maintenance, open issues, licence and size. Every dependency is code you trust and must keep updated; for small tasks, a few lines of your own code may be better than a new dependency.

Common mistakes#

Practice#

{
  "scripts": {
    "today": "node -e \"console.log(new Date().toISOString().slice(0, 10))\""
  }
}

Key takeaway#

Next: Working with Files (fs).