package.json

Learning objectives#

• Read every common package.json field
• Write npm scripts and run them
• Understand semver ranges like ^1.2.3 and ~1.2.3
• Set the module type and Node engine

Explanation#

name and version identify the package; private: true stops accidental publishing to npm.

"type": "module" makes .js files ES modules (import/export). Without it, Node treats .js as CommonJS (require).

scripts are named commands: "dev": "node --watch server.js". Run them with npm run dev; start and test also work as npm start and npm test.

Semantic versioning MAJOR.MINOR.PATCH: ^5.1.0 allows 5.x.x (no new major), ~5.1.0 allows 5.1.x, 5.1.0 is exact.

"engines": { "node": ">=22" } documents (and with engine-strict, enforces) the Node version. main / exports tell Node which file to load when someone imports your package.

Syntax#

1{
2  "name": "shop-api",
3  "version": "1.0.0",
4  "private": true,
5  "type": "module",
6  "scripts": { "dev": "node --watch server.js", "start": "node server.js", "test": "node --test" },
7  "dependencies": { "express": "^5.1.0" },
8  "devDependencies": { "eslint": "^9.0.0" },
9  "engines": { "node": ">=22" }
10}

Code example: Reading package.json and checking semver ranges#

1// Node can import JSON with an import attribute
2import pkg from './package.json' with { type: 'json' };
3

4console.log(`${pkg.name}@${pkg.version} (type: ${pkg.type})`);
5console.log('Scripts:', Object.keys(pkg.scripts).join(', '));
6

7// What does each range allow? A tiny semver check for MAJOR.MINOR.PATCH
8function allows(range, version) {
9  const [maj, min, pat] = version.split('.').map(Number);
10  const [rMaj, rMin, rPat] = range.replace(/[\^~]/, '').split('.').map(Number);
11  if (range.startsWith('^')) return maj === rMaj && (min > rMin || (min === rMin && pat >= rPat));
12  if (range.startsWith('~')) return maj === rMaj && min === rMin && pat >= rPat;
13  return version === range;
14}
15

16for (const v of ['5.1.0', '5.1.9', '5.4.2', '6.0.0']) {
17  console.log(v.padEnd(6), '^5.1.0:', allows('^5.1.0', v), ' ~5.1.0:', allows('~5.1.0', v));
18}
19

20// package.json used for this example:
21// { "name": "shop-api", "version": "1.0.0", "type": "module",
22//   "scripts": { "dev": "node --watch server.js", "start": "node server.js", "test": "node --test" } }

shop-api@1.0.0 (type: module)
Scripts: dev, start, test
5.1.0  ^5.1.0: true  ~5.1.0: true
5.1.9  ^5.1.0: true  ~5.1.0: true
5.4.2  ^5.1.0: true  ~5.1.0: false
6.0.0  ^5.1.0: false  ~5.1.0: false

This example is illustrative. Copy or download it and run it in your own environment; the expected output is shown above.

Step-by-step explanation#

1. import ... with { type: "json" } loads package.json as an object.
2. scripts lists the commands you can run with npm run <name>.
3. ^5.1.0 accepts any 5.x version from 5.1.0 up — minor and patch updates.
4. ~5.1.0 accepts only patch updates within 5.1.x.
5. Neither accepts 6.0.0: a new major version may contain breaking changes.

Real-world use case#

Common mistakes#

Best practices#

• Set "private": true for apps
• Use scripts for every common task
• Declare engines.node
• Keep dependencies lean and up to date

Remember this#

Practice exercise#

1{
2  "scripts": {
3    "dev": "node --watch server.js",
4    "start": "node server.js",
5    "test": "node --test",
6    "lint": "eslint ."
7  }
8}

Mini quiz#

Want more? Practise all Node.js MCQs · Node.js interview questions

Related topics#

My notes#

Saved in this browser.