npm & Packages

Managing dependencies, scripts, and publishing packages — package.json, semver, npm vs pnpm vs Bun, lockfiles, and workspace patterns.

What it is, in plain English: npm (Node Package Manager) is the default package manager for Node.js. package.json declares your project's name, version, scripts, and dependencies. npm install downloads dependencies to node_modules and records exact versions in package-lock.json. Semantic versioning (semver) uses MAJOR.MINOR.PATCH: 1.0.0 → breaking.feature.fix. pnpm and Bun are faster alternatives to npm with the same package.json format.

Where this bites you

package.json is strict JSON, not JavaScript. A // comment or a trailing comma, both perfectly fine in a .js file, make it unreadable, and then every npm command in the project fails with EJSONPARSE, including npm install and npm run. The annotated examples on this page use // comments to explain each field, so copy the fields, not the comments.

{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",           // "module" for ESM
  "scripts": {
    "start": "node src/index.js",
    "test":  "node --test",
  }
}
// $ npm run start
// npm error code EJSONPARSE
// npm error JSON.parse Invalid package.json: JSONParseError: Expected double-quoted property name in JSON at position 74 (line 4 column 31) ...
// npm error JSON.parse Note: package.json must be actual JSON, not just JavaScript.

Managing project dependencies

Creating a new project

mkdir my-project && cd my-project
npm init -y          # creates package.json with defaults
# or: pnpm init / bun init

Installing packages

# Install a runtime dependency:
npm install express
npm install zod dotenv

# Install a dev dependency (only for development, not production):
npm install -D vitest eslint typescript

# Install a specific version:
npm install react@18.2.0

# Install globally (for CLI tools):
npm install -g nodemon
# Better: use npx to run without global install:
npx vitest  # downloads and runs vitest without installing

package.json — what the fields mean

{
  "name":        "my-app",
  "version":     "1.0.0",           // must follow semver
  "type":        "module",           // "module" for ESM, omit for CommonJS
  "scripts": {
    "start":     "node src/index.js",
    "dev":       "nodemon src/index.js",  // run: npm run dev
    "test":      "vitest",
    "build":     "tsc"
  },
  "dependencies": {
    "express":   "^4.18.2"          // runtime — needed in production
  },
  "devDependencies": {
    "vitest":    "^1.0.0",          // dev only — not shipped to production
    "typescript":"^5.3.0"
  },
  "engines": {
    "node": ">=18.0.0"              // minimum Node.js version
  }
}

Keep package.json to plain JSON: double-quoted keys and strings, no comments and no trailing commas. Let tools edit it for you where they can (npm install, npm pkg set), and if you need notes, put them in the README:

{
  "name": "my-app",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "test": "node --test"
  }
}
// $ npm run start
// > node src/index.js
// app started

Semantic versioning (semver)

// Version format: MAJOR.MINOR.PATCH
// 1.2.3
//  ↑ ↑ ↑
//  │ │ └─ PATCH: bug fixes (backwards-compatible)
//  │ └─── MINOR: new features (backwards-compatible)
//  └───── MAJOR: breaking changes

// Semver ranges in package.json:
"express": "^4.18.2"   // ^ = compatible: 4.18.2 to <5.0.0
"express": "~4.18.2"   // ~ = patch only: 4.18.2 to <4.19.0
"express": "4.18.2"    // exact version only

Try It Yourself

// package.json — the heart of every Node.js project
// This runs in the browser to demonstrate the concepts

// A complete package.json:
const packageJson = {
  "name":     "my-awesome-api",
  "version":  "1.2.3",          // MAJOR.MINOR.PATCH
  "description": "A REST API built with Node.js",
  "main":     "dist/index.js",  // CJS entry point
  "module":   "dist/index.mjs", // ESM entry point
  "type":     "module",         // "module" = ESM, "commonjs" = CJS (default)

"scripts": {
    "start":   "node dist/index.js",
    "dev":     "node --watch src/index.js",  // Node 18+ watch mode
    "build":   "tsc",
    "test":    "vitest run",
    "lint":    "eslint src/",
    "prepare": "npm run build",  // runs before npm publish
  },

"dependencies": {
    "express":   "^4.18.2",    // ^ = any compatible version (4.x.x)
    "zod":       "^3.22.0",
    "dotenv":    "^16.3.1",
  },

"devDependencies": {
    "vitest":    "^1.0.0",
    "eslint":    "^8.55.0",
    "typescript":"^5.3.0",
  },

"engines": { "node": ">=18.0.0" },
  "license": "MIT",
};

console.log("package.json structure:");
console.log(JSON.stringify(packageJson, null, 2).slice(0, 500) + "...");

// SEMVER — Semantic Versioning:
const versions = {
  "^1.2.3":  "MINOR and PATCH updates allowed (1.x.x ≥ 1.2.3)",
  "~1.2.3":  "PATCH updates only (1.2.x ≥ 1.2.3)",
  "1.2.3":   "Exact version only",
  ">=1.0.0 <2.0.0": "Range: 1.x.x",
  "*":       "Any version (dangerous!)",
  "latest":  "Whatever is latest on npm (very dangerous!)",
};

console.log("\nSemver ranges:");
Object.entries(versions).forEach(([range, desc]) =>
  console.log(`  ${range.padEnd(20)} → ${desc}`)
);

// Common commands:
const commands = [
  ["npm install",           "install all deps from package.json"],
  ["npm install express",   "add express to dependencies"],
  ["npm install -D vitest", "add vitest to devDependencies"],
  ["npm uninstall express", "remove a package"],
  ["npm update",            "update all packages to max allowed range"],
  ["npm audit",             "check for security vulnerabilities"],
  ["npm run build",         "run the 'build' script"],
  ["npx create-react-app", "run without installing globally"],
];

console.log("\nCommon npm commands:");
commands.forEach(([cmd, desc]) => console.log(`  ${cmd.padEnd(30)} # ${desc}`));

Scripts, lockfiles, and npm vs pnpm vs Bun

npm scripts — automate everything

{
  "scripts": {
    // Lifecycle scripts — run automatically:
    "prepare":  "npm run build",       // before: npm publish, npm install
    "pretest":  "npm run lint",        // before: npm test
    "postbuild":"cp -r public dist/",  // after: npm run build

    // Custom scripts — run with: npm run <name>
    "dev":      "node --watch src/index.js",
    "build":    "tsc && tsc-alias",
    "test":     "vitest run",
    "test:watch": "vitest",
    "lint":     "eslint src --fix",
    "start":    "node dist/index.js",

    // Combining commands (cross-platform with npm-run-all):
    "check":    "npm run lint && npm run test && npm run build",
  }
}

package-lock.json — exact reproducible installs

// package.json specifies ranges (^4.18.2 = any 4.x.x)
// package-lock.json records the EXACT version installed:
// "express": { "version": "4.18.2", "resolved": "...", "integrity": "sha512-..." }

// ALWAYS commit package-lock.json to version control!
// npm ci (not npm install) reads the lockfile exactly — for CI/CD:
npm ci  // faster, deterministic, fails if lockfile is outdated

// pnpm-lock.yaml for pnpm, bun.lock for Bun (binary bun.lockb before Bun 1.2)

npm vs pnpm vs Bun

npm

pnpm

Bun

Speed

Baseline

2-3x faster

10-30x faster

Disk space

Per-project

Shared (hard links)

Shared

node_modules

Flat tree

Virtual (symlinks)

Different

Workspaces

Yes (v7+)

Yes (best)

Yes

Mature

Most

Very

Less so

Workspaces, publishing, and resolution algorithm

// Monorepo workspaces — manage multiple packages in one repo:
// package.json (root):
// { "workspaces": ["packages/*", "apps/*"] }

// pnpm-workspace.yaml:
// packages: ["packages/*", "apps/*"]

// Reference a local workspace package:
// "dependencies": { "@myco/ui": "workspace:*" }

// npm publish — sharing a package:
// 1. Ensure "name", "version", "main"/"exports" are set
// 2. Add "files" to control what's published:
//    "files": ["dist/", "README.md"]
// 3. npm login && npm publish
// 4. npm publish --tag beta  (for pre-releases)

// Node.js module resolution (CommonJS):
// require("express")
// → look in node_modules/express
// → read node_modules/express/package.json → "main"
// → load that file

// ESM resolution:
// import "express"
// → package.json "exports" field (conditional exports)
// exports: { "import": "./dist/index.mjs", "require": "./dist/index.cjs" }

// Conditional exports — different files for different environments:
{
  "exports": {
    ".": {
      "import":  "./dist/index.mjs",   // ESM
      "require": "./dist/index.cjs",   // CJS
      "browser": "./dist/browser.js",  // bundlers for browser
    },
    "./utils": "./dist/utils.mjs"
  }
}

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.