Nothing kills development momentum faster than a package manager error. You initialize a new React project, attempt to install the industry-standard eslint-config-airbnb, and immediately hit a wall of red text starting with ERESOLVE unable to resolve dependency tree.
For years, eslint-config-airbnb has been the gold standard for maintaining code quality in JavaScript teams. However, since the release of npm 7 (and continuing into npm 8, 9, and 10), installing this configuration has become a source of significant frustration.
This guide provides the technical root cause of this failure and details two robust methods to resolve it, ensuring your linting pipeline works correctly in modern CI/CD environments.
The Root Cause: Why ERESOLVE Happens
To fix the problem effectively, you must understand the algorithmic change introduced in npm 7.
In older versions of npm (v4 through v6), peer dependencies were largely advisory. If a package requested peerDependencies, npm would warn you if they were missing but would not fail the installation. It assumed the developer would handle the discrepancy.
Starting with npm 7, the installer attempts to automatically install peer dependencies. It also enforces strict tree resolution to ensure deterministic builds.
The Dependency Collision
The eslint-config-airbnb package is a collection of specific linting rules that relies on exact versions of other plugins to function correctly. These typically include:
eslint-plugin-importeslint-plugin-reacteslint-plugin-react-hookseslint-plugin-jsx-a11y
The error occurs because eslint-config-airbnb strictly pins these dependencies. If your project already has a newer version of eslint or a different version of a React plugin installed (which create-react-app or Vite might do by default), npm detects a version conflict. It cannot mathematically satisfy the strict version requirement of Airbnb's config alongside the version already present in your node_modules tree.
Consequently, npm throws an ERESOLVE error to prevent creating a broken dependency tree.
Solution 1: The install-peerdeps Utility (Recommended)
The most reliable, production-safe method to install the Airbnb config is using the install-peerdeps CLI tool. This utility is specifically maintained to handle the complexity of peer dependency versioning.
Instead of guessing which versions of the plugins match the specific version of the config you are installing, this tool queries the npm registry, fetches the peer dependency list defined by the package maintainers, and constructs a compatible installation command.
Step-by-Step Implementation
- Run the command via npx. Do not install the tool globally; run it on-demand to ensure you use the latest logic.
npx install-peerdeps --dev eslint-config-airbnb
- Verify the output. The tool will detect your package manager (npm or yarn) and execute a command similar to the one below automatically:
# Example of what the tool executes under the hood:
npm install --save-dev eslint-config-airbnb eslint@^8.2.0 eslint-plugin-import@^2.25.3 eslint-plugin-jsx-a11y@^6.5.1 eslint-plugin-react@^7.28.0 eslint-plugin-react-hooks@^4.3.0
This method is superior because it ensures that the installed plugins are the exact versions tested against the Airbnb ruleset, eliminating runtime crashes caused by rule definition mismatches.
Solution 2: The --legacy-peer-deps Flag
If you cannot use external executables like install-peerdeps due to security policies, or if you are integrating this into an existing complex package.json, you can instruct npm to revert to its pre-v7 behavior.
This method tells npm: "Ignore the peer dependency tree conflicts and install the package anyway."
execution
Run the standard install command appended with the flag:
npm install eslint-config-airbnb --save-dev --legacy-peer-deps
Technical Warning
While --legacy-peer-deps fixes the immediate installation error, it transfers the responsibility of version compatibility back to the engineer. You may encounter warnings during the linting process if the Airbnb config expects a rule that does not exist in the version of the plugin npm decided to install.
Do not use --force. The --force flag will overwrite existing modules in node_modules, potentially breaking other dependencies. --legacy-peer-deps is safer as it simply skips the strict resolution step.
Configuration and Setup
Once the packages are installed, you must configure ESLint to consume the new ruleset.
1. Create the Config File
Create an .eslintrc.json file in your root directory.
{
"extends": [
"airbnb",
"airbnb/hooks"
],
"env": {
"browser": true,
"node": true,
"es2022": true
},
"rules": {
"react/react-in-jsx-scope": "off",
"no-console": "warn"
}
}
Note: If you are using React 17+ (which introduced the new JSX transform), you should disable react/react-in-jsx-scope, as importing React is no longer required in JSX files.
2. Add Scripts to Package.json
Add explicit linting scripts to your package.json to normalize execution across your team.
{
"scripts": {
"start": "react-scripts start",
"lint": "eslint . --ext .js,.jsx",
"lint:fix": "eslint . --ext .js,.jsx --fix"
}
}
Handling TypeScript Projects
If you are working with TypeScript, installing eslint-config-airbnb alone is insufficient. You need the TypeScript extension of the config to handle type-specific linting and prevent false positives on interfaces and types.
installation
Use the same install-peerdeps strategy for the TypeScript variant:
npx install-peerdeps --dev eslint-config-airbnb-typescript
Configuration Update
You must point the parser to your tsconfig.json file so ESLint can understand your project's type topology.
{
"extends": [
"airbnb",
"airbnb-typescript"
],
"parserOptions": {
"project": "./tsconfig.json"
},
"rules": {
"react/jsx-filename-extension": [1, { "extensions": [".tsx", ".ts"] }]
}
}
Troubleshooting: React Version Conflicts
A common edge case occurs when your project uses a bleeding-edge version of React (e.g., React 19 Alpha) while the Airbnb config is pinned to stable React versions.
If install-peerdeps fails, or if you see runtime errors regarding missing package exports, you may need to explicitly modify your package.json overrides (a feature available in npm 8.3+).
Add this to your package.json to force dependency resolution to align with your project's React version:
{
"overrides": {
"eslint-plugin-react": "$eslint-plugin-react"
}
}
This tells npm to ensure that the version of eslint-plugin-react used by sub-dependencies matches the root version installed in your project, flattening the dependency tree manually.
Conclusion
The ERESOLVE error is not a bug in npm; it is a safety feature protecting the integrity of your node_modules. However, for highly opinionated configurations like Airbnb's, it requires a workaround.
For 95% of use cases, npx install-peerdeps --dev eslint-config-airbnb is the correct, professional solution. It aligns the versions exactly as the maintainers intended, preventing "it works on my machine" issues and ensuring your CI pipeline remains stable.