Resolving NPM/Yarn Dependency Conflicts in React Projects

Dependency conflicts are among the most frustrating build issues in JavaScript projects. Here’s a comprehensive guide to identifying and resolving these conflicts:

Identifying Dependency Conflicts

Common Symptoms:

• ERESOLVE errors during installation
• Inconsistent behavior between development and production
• Missing peer dependency warnings
• “Module not found” errors for installed packages
• Version mismatch warnings

Step-by-Step Solutions

1. Basic Clean and Reinstall

# For npm projects
rm -rf node_modules package-lock.json
npm install

# For Yarn projects
rm -rf node_modules yarn.lock
yarn install

2. Check for Version Conflicts

npm ls <package-name>  # Shows all installed versions
yarn why <package-name>  # Yarn's version of the same

3. Update All Dependencies

# Using npm
npm outdated
npm update

# Using Yarn
yarn upgrade-interactive

4. Resolve Peer Dependency Issues

# View peer dependency issues
npm ls --all

# Install missing peer deps
npm install --legacy-peer-deps
# or for permanent solution
npm config set legacy-peer-deps true

Advanced Resolution Techniques

1. Manual Resolution in package.json

"resolutions": {
  "react": "18.2.0",
  "react-dom": "18.2.0"
}

Then run:

yarn install

2. Using Dependency Overrides (npm)

"overrides": {
  "react": "18.2.0",
  "react-dom": "18.2.0"
}

3. Selective Package Installation

npm install package@version --force
yarn add package@version --ignore-engines

Preventing Future Conflicts

1. Pin Exact Versions

"dependencies": {
  "react": "18.2.0",  # Exact version
  "react-dom": "~18.2.0"  # Patch updates only
}

2. Use Consistent Package Manager

# Set npm as default
npm config set save-exact true

# Or for Yarn
yarn config set save-exact true

3. Implement Workspaces (for Monorepos)

"workspaces": {
  "packages": [
    "packages/*"
  ],
  "nohoist": [
    "**/react-native",
    "**/react-native/**"
  ]
}

Debugging Tools

1. Visualize Dependency Tree

npm install -g npm-why
npm-why <package-name>

2. Check for Duplicate Packages

npx yarn-deduplicate
# or
npm dedupe

3. Audit Dependencies

npm audit
yarn audit

Common Conflict Scenarios

React Version Conflicts

# Force correct React version
npm install react@18.2.0 react-dom@18.2.0

Webpack Loader Conflicts

# Ensure matching major versions
npm install webpack@5 webpack-cli@4

Babel Preset Conflicts

"devDependencies": {
  "@babel/core": "^7.20.0",
  "@babel/preset-env": "^7.20.0",
  "@babel/preset-react": "^7.18.6"
}

CI/CD Considerations

Add these steps to your CI pipeline:

- name: Cache node_modules
  uses: actions/cache@v3
  with:
    path: node_modules
    key: ${{ runner.os }}-modules-${{ hashFiles('**/yarn.lock') }}

- name: Install dependencies
  run: yarn install --frozen-lockfile

Remember to:

1. Document all manual resolutions
2. Regularly update dependencies
3. Use lockfiles consistently across environments
4. Consider tools like Dependabot for automated updates