Dependencies in package.json

Breakdown of how JavaScript projects handles different types of dependencies.

If you've worked on a Node.js or frontend project, you've seen package.json. This humble file is the heart of any JavaScript project—it tracks your project's metadata, scripts, and, most importantly, its dependencies. But not all dependencies are the same. Knowing the difference between dependencies, devDependencies, peerDependencies, and optionalDependencies helps you write clearer code, avoid bloated production bundles, and better collaborate across teams.

Dependencies

dependencies are the packages your project needs to run in production. If your code imports something like axios or react, it belongs here. When someone installs your project, these packages come along because they're required for your app to function.

Development Dependencies

Use —-save-dev flag to add entry

devDependencies are only needed during development—think eslint, webpack, or jest. They help you lint, build, or test your project but aren’t necessary for running it in the wild. Keeping them separate from regular dependencies prevents unnecessary installs in production environments and helps keep your deployed app lighter and faster.

Peer Dependencies

There is no flag to add a peer dependency using the npm CLI.

Then there’s peerDependencies, which signal that your code is compatible with—but doesn’t directly install—a specific package. For example, a React component library might list react as a peer dependency to ensure the host app provides its own version of React. This avoids duplicate or conflicting versions.

Optional Dependencies

Use —-save-optional flag to add entry

Lastly, optionalDependencies are just that—optional. They’ll be installed if possible, but failure to install them won’t break the project. These are useful for platform-specific tools or features that enhance your app but aren’t critical. Understanding these categories ensures your project stays lean, efficient, and easy to maintain—no dependency drama required.