Node CLI, npm, and package.json essentials.
A quick reference for the Node.js runtime and npm — the CLI flags, package commands, and `package.json` fields that come up when you set up or maintain a project.
The semver section is the one people misread: `^1.2.3` and `~1.2.3` allow different ranges of updates, and knowing which is which is the difference between a safe `npm update` and a surprise breaking change.
node file.js | Run a script. |
node --watch file.js | Re-run on file changes (Node 18.11+). |
node --env-file=.env file.js | Load env vars from a file (Node 20.6+). |
node --inspect file.js | Start with the debugger attached. |
node -v · node -e "code" | Print version; run inline code. |
npm install · npm ci | Install deps; ci does a clean, lockfile-exact install. |
npm install pkg · npm i -D pkg | Add a dependency; -D for devDependencies. |
npm uninstall pkg | Remove a dependency. |
npm run <script> · npm start | Run a package.json script. |
npm outdated · npm update | List outdated deps; update within ranges. |
npx <pkg> | Run a package binary without installing globally. |
"type": "module" | Treat .js files as ES modules (import/export). |
"scripts": { "dev": "..." } | Named commands run via npm run. |
"engines": { "node": ">=20" } | Declare the required Node version. |
"main" · "exports" | Entry point; exports defines the public API map. |
"dependencies" vs "devDependencies" | Runtime deps vs build/test-only deps. |
How a version range in package.json is interpreted.
^1.2.3 | Allows 1.x.x up to <2.0.0 (minor + patch). |
~1.2.3 | Allows 1.2.x up to <1.3.0 (patch only). |
1.2.3 | Exact version only. |
>=1.2.0 <2.0.0 | Explicit range. |
* · latest | Any version — avoid in libraries. |
`npm install` resolves dependencies and may update `package-lock.json`. `npm ci` does a clean install strictly from the lockfile — it deletes `node_modules` first and fails if the lockfile and `package.json` disagree. Use `npm ci` in CI and deployments for reproducible builds.
`^1.2.3` allows any release compatible with 1.2.3 under semver — that is, up to but not including 2.0.0, so new minor and patch versions are accepted. `~1.2.3` is stricter, allowing only patch updates (up to <1.3.0).