React Dependency Types Explained: What Goes Where in package.json (With Real Examples)

Introduction

When you're working with a React project, you'll often add other packages or tools to help build or run your app. These are called dependencies, and they’re listed in a file called package.json.

But not all dependencies are the same — some are needed in production, some only during development, and some are required only when building reusable libraries.

In this guide, we’ll explain:

• What dependencies are
• What devDependencies are
• What peerDependencies are

with real examples so you can understand when and how to use each.

What are dependencies?

These are the packages your app needs to work when it runs — especially after it's been built and deployed.

When you install a package like this:

it gets added to the dependencies section of package.json.

These will be part of your app’s final bundle that runs in users' browsers.

So here, axios is used for making API calls, and React is your main library. Both are necessary for your app to function properly.

Example:

What are devDependencies?

These packages are only needed while you're developing the app — not when the app is live.

They include things like:

• Code formatters (eslint)
• Build tools (vite)
• Test frameworks (jest)
• Type checkers (typescript)

You install them using:

They’ll be added to the devDependencies section in package.json.

Example:

When you build your app, these tools help prepare your code — but they’re not included in the final bundle sent to the browser.

What are peerDependencies?

These are a little different. You use peerDependencies mostly when you’re creating a library or shared component, not a full app.

A peerDependency tells the user of your library:

“Hey! You need to have this package installed for my library to work.”

Your library expects the host app to already have that package — usually something like react.

Why do we use this?

If your library includes its own version of React, and the host app uses a different version, they might conflict. That can break things like hooks, context, or even throw errors.

By using peerDependencies, you avoid including React yourself and instead rely on the version the main app already uses.

Example:

This says: “Your project should have a React version that matches one of these.”
npm will warn the user if they don’t.

How npm Handles These Dependencies

When you run:

Here’s what happens for each dependency type:

• dependencies are always installed and included in the final build.
• devDependencies are only installed in development, not in production if you set NODE_ENV=production.
• peerDependencies are not installed automatically in older npm versions (v6 and below).
• In npm v7+, they try to install them — but only if versions match properly.

Example:

Here:

• axios is required to run your app.
• jest is for testing during development.
• react is expected to be provided by whoever installs your package.

Common Mistakes to Avoid

Here are some mistakes many developers make:

• Putting everything into dependencies, even tools that are only needed during development.
• Not adding peerDependencies in libraries — which leads to duplicate versions and weird errors.
• Including React in both the app and your custom library, causing conflict between React versions.

 

Conclusion

Understanding these three types of dependencies can really improve your project setup:

• Use dependencies for the actual code your app runs.
• Use devDependencies for tools that help you build and test.
• Use peerDependencies when building packages that need shared libraries (like react).

By keeping these organized, your project will stay clean, efficient, and easier to maintain - especially when working with multiple developers or publishing reusable components.