npm: Fundamentals & package.json

npm is the default package manager for Node.js. It ships with Node.js and manages packages (libraries) for your project. package.json is the manifest file describing your project and its dependencies.

npm vs yarn vs pnpm

• npm: built into Node.js, most universal, v10+ is fast. Lock file: package-lock.json.

• yarn (classic): was faster than npm in 2016, introduced yarn.lock. yarn berry (v2+): PnP mode, corepack — complex, avoid unless you know why.

• pnpm: fastest, most disk-space-efficient (hard-links), strict about phantom dependencies. Lock file: pnpm-lock.yaml. Excellent for monorepos.

• Recommendation: pnpm for new projects; npm for maximum compatibility; avoid yarn classic in new codebases.

package.json — Key Fields

{
  "name": "@myorg/my-package",
  "version": "1.2.3",
  "description": "Short description of what this does",
  "license": "MIT",
  "author": "Alice <alice@example.com>",

  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./utils": {
      "import": "./dist/utils.mjs",
      "types": "./dist/utils.d.ts"
    }
  },
  "types": "./dist/index.d.ts",

  "files": ["dist", "!dist/**/*.test.*"],

  "scripts": {
    "build": "tsc",
    "test": "vitest",
    "lint": "eslint src"
  },

  "engines": {
    "node": ">=18.0.0",
    "npm": ">=9.0.0"
  },

  "dependencies": {
    "zod": "^3.22.0"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "vitest": "^1.0.0"
  },
  "peerDependencies": {
    "react": ">=18.0.0"
  },
  "peerDependenciesMeta": {
    "react": { "optional": true }
  },

  "keywords": ["utility", "typescript"],
  "repository": {
    "type": "git",
    "url": "https://github.com/myorg/my-package.git"
  },
  "bugs": "https://github.com/myorg/my-package/issues",
  "homepage": "https://mypackage.dev"
}

Semantic Versioning

Version: MAJOR.MINOR.PATCH  (e.g. 2.4.1)

MAJOR — breaking changes
MINOR — new features, backward compatible
PATCH — bug fixes

Range specifiers in package.json:
  "^3.4.1"   — compatible (same major): >=3.4.1 <4.0.0  ← default npm behavior
  "~3.4.1"   — approximate (same minor): >=3.4.1 <3.5.0
  "3.4.1"    — exact version pinned
  ">=3.4.1"  — at least this version
  "*"        — any version (dangerous)
  "3.x"      — any 3.x.x
  "3.4.x"    — any 3.4.x

Pre-release tags:
  "1.0.0-alpha.1"
  "1.0.0-beta.2"
  "1.0.0-rc.1"

package-lock.json

The lock file records exact versions of every installed package (including transitive dependencies). It ensures reproducible installs across machines and CI. Always commit it to version control. Never edit it manually.

• npm install: installs what package.json specifies, may update lock file

• npm ci: installs EXACTLY what lock file specifies (fails if package.json and lock mismatch). Use in CI.

• Lock file conflict in PRs: run npm install after resolving package.json conflict, then commit the regenerated lock file.