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.

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
  }
}

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.lockb for Bun

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.