Peer Dependencies

  • javascript
  • npm
  • your project – your project
  • parent project – project that has your project as a dependency

Peer dependencies area a special type of dependency that your project requires, but the parent project (the one using your project) is responsible for installing them.

Simply put: “My project needs this dependency. But whoever uses my project will be responsible for installing it”.

{
	"name": "your_project",
	"version": "1.0.0",
	"peerDependencies": { 
		"react": "^17.0.0" 
	}
}
// ---
{
	"name": "parent_project",
	"dependencies": { 
		"your_project": "^1.0.0",
		"react": "17.0.0" 
	}
}

Peer dependencies also have a defined version that is compatible with your project. The parent project must ensure that its version matches the one defined by your project.

Since npm@7, the system automatically installs peer dependencies if they aren’t defined in your project. But when you try to install another dependency with a conflicting version, you’ll receive error.

Benefits

  1. Smaller node_modules – Your project doesn’t duplicate dependencies but uses versions already installed by the parent project. This saves disk space and speeds up installation.
  2. Lighter production code – Your project and the parent project use the same dependencies, which positively affects size and performance. Additionally, if the built project contained two instances of the same dependency, compatibility problems could occur, leading to errors that are sometimes difficult to diagnose.
  3. Clear version compatibility – When the dependency version required by your project doesn’t match the version in the parent project, npm will display a warning or error and won’t complete the installation. This allows for quick response and project updates.

When to use?

All projects that build on the functionality of other projects or are based on them, for example:

Peer Dependencies Metadata

In package.json, you’ll also find peerDependenciesMeta. This field allows you to provide additional information about peer dependencies. Since npm@7, the optional option is available, which as the name suggests, will make the dependency not required to be installed by the parent project. Additionally npm won’t automatically install optional peer dependencies.

{
	"name": "your_project",
	"peerDependencies": { 
		"react": "^18.0.0",
		"typescript": "^3.0.0"
	},
	"peerDependenciesMeta": {
		"typescript": {
			"optional": true
		}
	}
}

Example of using peerDependenciesMeta by Vuetify.

Bibliography