Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 36 ยท Packages and package.json

Dependencies, devDependencies and peerDependencies

Understand the five dependency fields in package.json, when each applies, how production installs skip devDependencies, and how peer and optional dependencies behave.

A package.json can list dependencies in several places, and choosing the right place changes who receives the package and when. Put a library in the wrong list and your users either download tools they never need or hit "module not found" in production. This lesson explains each list and gives you a simple rule for choosing.

The five lists

Field Installed for you Installed for people who depend on you Typical content
dependencies Yes Yes Code your package needs at runtime
devDependencies Yes No Test runners, linters, build tools
peerDependencies Depends on the manager Must be supplied by the consumer Plugin hosts such as react
optionalDependencies Tries to Tries to Speed-ups; failure is allowed
bundleDependencies Yes Included inside the tarball Rare; vendoring

Everything below uses these commands (read-only):

Terminal
npm install express            # dependencies
npm install --save-dev vitest  # devDependencies (short: -D)
npm install --save-peer react  # peerDependencies (npm 7+)
npm install --save-optional fsevents

dependencies

Anything your code imports while it runs belongs here. If your application imports express, then express is a dependency. When someone installs your package, npm installs your dependencies too, recursively.

devDependencies

Tools you need only while developing: test frameworks, linters, formatters, type checkers, bundlers. They are installed when you run npm install inside your own project but not when your package is installed as someone else's dependency, and not on a production server if you install with npm install --omit=dev (older spelling: --production).

Node.js Production install: what is kept?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A bundled front-end app is a special case: the build tool turns your imports into a single file, so even libraries like react are often put in devDependencies. The rule is about what the deployed runtime needs, not what the code imports.

peerDependencies

A peer dependency says: "I work with this package, but you must install it yourself." A React component library does not ship its own React; it declares react as a peer so the app and the library share exactly one copy. Two copies of React in one page break hooks.

JSON
{
  "name": "acme-button",
  "peerDependencies": { "react": ">=18" },
  "peerDependenciesMeta": { "react": { "optional": false } }
}

npm 7 and later install missing peers automatically and fail with an ERESOLVE error if versions conflict. pnpm and Yarn warn about missing or mismatched peers by default. peerDependenciesMeta can mark a peer as optional, so the warning disappears when it is absent.

optionalDependencies

If an optional package fails to install (for example a native speed-up that needs a compiler), the install still succeeds. Your code must then handle its absence:

Node.js Handling an optional dependency

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Never list something in optionalDependencies that your code needs unconditionally. It is not "a softer dependencies", it means "may be absent".

The rule of thumb

Node.js Which list does it belong in?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Moving between lists

You can edit package.json by hand, or reinstall with another flag: npm install -D vitest moves it to devDependencies. After editing by hand, run npm install so the lockfile matches. The same package should never appear in two lists; if it does, tools disagree about which wins.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does a test runner such as vitest belong?

    Tools used only for development and tests go in devDependencies.
  2. 2. Why does a React component library list react as a peerDependency?

    Two copies of React in one app break hooks; the consumer supplies it.
  3. 3. What does npm install --omit=dev do?

    It is the production-style install, leaving out devDependencies.
  4. 4. What must your code do with an optionalDependency?

    Installation may fail silently, so the import must be guarded.

Summary

  • dependencies are needed at runtime and travel with your package.
  • devDependencies are for building and testing and are not installed for consumers.
  • peerDependencies ask the consumer to provide a shared package.
  • optionalDependencies may fail to install; guard the import.
  • Use --omit=dev for production installs.

Next: How node_modules and Resolution Work