skip to content

Package Manifest & Semver

The package.json fields npm acts on: peer and optional dependencies, overrides, engines, bin and exports, and how npm saves and updates a range. Asked because one manifest line decides what installs.

on this pageshow

questions

6

In an npm project, what is the difference between `dependencies` and `devDependencies`, and what does `npm install --omit=dev` leave out?

level: juniorimportance: must knowfreq 42%

answer

  1. who needs the package at runtime
  2. build and test tooling
  3. -D on npm install
  4. what a consumer's install brings in
  5. --omit=dev, still in the lockfile

basics

~20 s

In package.json, dependencies are packages the code needs at runtime and install for anyone who installs the package; devDependencies are build and test tools. npm install --omit=dev keeps devDependencies off disk while still recording them in the lockfile.

solid answer

~40 s

`dependencies` holds what the code needs at runtime; when another project installs your package, npm installs these too. `devDependencies` holds what you need to build, lint and test it; npm installs them when you run `npm install` at the root of the package, but a consumer's install does not put them into its tree. `npm install <pkg>` saves to `dependencies` by default, and `-D` / `--save-dev` saves to `devDependencies`. For a production image you run `npm ci --omit=dev` (or `npm install --omit=dev`): devDependencies are still resolved and kept in `package-lock.json`, they are just not written to `node_modules`. `--omit=dev` is also the default when `NODE_ENV=production`; the older `--production` flag survives only as a deprecated alias for it.

go deeper

for a junior

Recall the runtime-versus-tooling split, that npm install <pkg> saves to dependencies, and that -D saves to devDependencies.

for a middle

Explain what each section means for a consumer's install and that --omit=dev changes only what lands on disk, not the lockfile.

for a senior

Diagnose the 'works locally, missing in the image' failure from NODE_ENV=production or --omit=dev, and keep a library's runtime list minimal for its consumers.

for a principal

Weigh a team rule for classifying packages, such as reviewing every new dependencies entry in a published library, against the friction it adds to everyday changes.

## Why npm has more than one dependency section A `package.json` does not just list packages; it says **who needs each one and when**. npm reads the section a package sits in to decide whether to install it, for whom, and whether a failure is fatal. For a component library such as `@fleetline/charts` that a dispatch dashboard installs, the split decides what lands in the dashboard's `node_modules` and what stays in the library author's workspace. | Section | Meant for | Installed when someone installs your package? | Saved by | |---|---|---|---| | `dependencies` | code your package runs | yes | `npm install <pkg>` (default), `-P` / `--save-prod` | | `devDependencies` | build, lint and test tools | no | `-D` / `--save-dev` | | `peerDependencies` | a host the consumer provides | yes for non-optional peers, by default since npm 7 | `--save-peer` | | `optionalDependencies` | nice-to-have packages | yes, but a failed install is not fatal | `-O` / `--save-optional` | This answer is about the first two; peers and optional dependencies have their own rules. ## `dependencies` against `devDependencies` - **`dependencies`** are what the code `require`s or `import`s when it runs. If `@fleetline/charts` renders SVG through an XML parser, that parser belongs here, because the dashboard needs it at runtime. - **`devDependencies`** are what you need to work on the source: a test runner, a linter, a TypeScript compiler, a bundler. npm's own docs put it plainly: someone using your module probably does not want to download and build your test or documentation framework. - When you run `npm install` **at the root of a package**, npm installs both sections, because you are developing it. - When another project installs your package **as a dependency**, npm installs your `dependencies` but does not put your `devDependencies` into its tree. - For an application that is never installed by anyone else, the split still matters: it is what a production install uses to decide what to leave out. ## What `npm install <pkg>` writes Adding a package with `npm install <pkg>` saves it into `dependencies` unless you say otherwise: 1. `npm install <pkg>` or `-P` / `--save-prod` writes to `dependencies`. 2. `-D` / `--save-dev` writes to `devDependencies`. 3. `-O` / `--save-optional` writes to `optionalDependencies`, and `--save-peer` writes to `peerDependencies`. 4. `--no-save` installs without touching `package.json`. The range written next to the name comes from the `save-prefix` config (default `^`), or an exact version with `--save-exact`. ## Production installs with `--omit=dev` The `omit` config lists dependency types to leave **off disk**: `dev`, `optional` and `peer`. Both `npm install` and `npm ci` accept it, which is why a container build commonly runs `npm ci --omit=dev`. - Omitted packages are **still resolved and recorded in `package-lock.json`**; npm only skips writing them into `node_modules`. Omitting therefore does not change what the lockfile records. - If `NODE_ENV` is `production`, `omit` defaults to `dev`, so a production environment variable alone changes what installs. - If a type appears in both `--include` and `--omit`, it is included. `--include=dev` is the way to get devDependencies back when `NODE_ENV=production` is set. - When the omit list contains `dev`, npm sets `NODE_ENV=production` for the lifecycle scripts it runs. - `--production` and `--only=prod` still parse, but npm's current config definitions mark both as deprecated aliases of `--omit=dev`; guides that use them describe the same idea with retired flags. ## Misplacements that bite - A runtime package filed under `devDependencies` works on every laptop, because a local `npm install` installs both sections, and then crashes in the production image built with `--omit=dev`, or in a consumer's app that never received it. - A build tool filed under `dependencies` does not break anything, but every consumer downloads it, and every production image carries it. - In a bundled frontend app the browser bundle already contains the runtime code, so the split mostly decides what the build server and any Node-side process install; it is still worth keeping honest, because the next person to add a server-rendered route relies on it. The rule of thumb an interviewer wants to hear: **put a package where the code that needs it runs**. If it is needed when the code executes, it is a dependency; if it is needed only to produce or check the code, it is a devDependency.

  • A package works locally but the production container fails with `Cannot find module` for it. What is the likely cause?
    It is listed under `devDependencies` while the code needs it at runtime. Locally `npm install` installs both sections; the image runs `npm ci --omit=dev` (or has `NODE_ENV=production`), so the package never reaches `node_modules`. Move it to `dependencies` with `npm install <pkg> --save-prod`, which also moves an existing entry out of `devDependencies`.
  • With `NODE_ENV=production` set on a build machine, how do you still install the test tools?
    Pass `--include=dev`. `NODE_ENV=production` makes `omit` default to `dev`, and npm resolves a type that appears in both `--include` and `--omit` in favour of including it. No change to `package.json` is needed.

  • devDependencies are not recorded in package-lock.json at all
  • npm install <pkg> saves to devDependencies by default
  • a consumer's install also installs the library's devDependencies
  • --omit=dev deletes devDependencies from package.json
  • NODE_ENV=production has no effect on what npm installs
open as a page

With npm 7 or later, how does npm treat a component library's `peerDependencies`, and what changes when `peerDependenciesMeta` marks one peer optional?

level: middleimportance: must knowfreq 22%

basics

~20 s

Since npm 7, a library's non-optional peerDependencies are installed automatically, so the app and the library share one copy of the host. A peer marked optional: true in peerDependenciesMeta is not installed; the app adds it when needed.

open as a page

In an npm package's package.json, what does `engines` do when a consumer's Node.js is outside its range, and what makes npm refuse?

level: middleimportance: should knowfreq 12%

basics

~20 s

The engines field declares the Node.js (and npm) versions a package supports; by default a mismatch only prints a warning and the install continues. Setting engine-strict=true makes npm refuse with EBADENGINE, and --force overrides even that.

open as a page

With npm, `npm outdated` shows Current 2.1.0, Wanted 2.4.3, Latest 3.0.1 for a package; what does each mean, and what does `npm update` change?

level: middleimportance: should knowfreq 26%

basics

~10 s

Current is the installed version, Wanted the highest version satisfying the package.json range, Latest the version tagged latest. npm update installs within the range (2.4.3) and leaves package.json alone unless run with --save.

open as a page

With npm 7 or later, an app moves its UI framework to version 5 and `npm install` stops with `ERESOLVE` because a chart library peers on `^4`; what happened, and what do `--legacy-peer-deps` and `--force` change?

level: seniorimportance: should knowfreq 18%

basics

~10 s

The app's viewlib@5 and the library's peer range ^4 must share one copy, which is impossible, so npm stops with ERESOLVE. --legacy-peer-deps ignores every peer; --force accepts the conflict. Neither makes the pair compatible.

open as a page

With npm, why does an `overrides` entry in a published library's package.json do nothing for the apps that install it, and how does an app force a patched transitive version instead?

level: seniorimportance: should knowfreq 16%

basics

~10 s

npm reads overrides only from the root project's package.json; entries in installed dependencies, workspaces included, are ignored. The app adds its own override, such as "xml-tiny-parser": "^2.8.4", in its root manifest and reinstalls.

open as a page