菜单
Diagnoses npm/yarn dependency conflicts, identifies cascading updates, and suggests safe upgrade paths for React/Node.js projects.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | dependency-conflict-resolver |
| description | Diagnoses npm/yarn dependency conflicts, identifies cascading updates, and suggests safe upgrade paths for React/Node.js projects. |
| scripts | [{"name":"analyze-dependencies","command":"node .github/skills/dependency-conflict-resolver/analyze-dependencies.js","description":"Checks package.json for compatibility issues (React ecosystem, version mismatches, outdated packages)"}] |
This skill helps diagnose and resolve npm dependency conflicts for FanHub's React frontend and Node.js backend.
Symptom:
npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: react-router-dom@6.20.0
npm ERR! Found: react@17.0.2
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.0.0" from react-router-dom@6.20.0
What This Means:
react-router-dom@6.20.0 requires React 18+Diagnostic Steps:
react-router-dom@6.20.0react@^18.0.0react@17.0.2Resolution:
# Check what else depends on React
npm list react
# Update related packages together
npm install react@^18.2.0 react-dom@^18.2.0 @testing-library/react@^13.0.0
The React Ecosystem Rule: These packages MUST be on the same major version:
reactreact-domreact-native (if used)Common Mismatch:
{
"react": "^17.0.2",
"react-dom": "^18.2.0" // ❌ Different major version!
}
Fix:
{
"react": "^18.2.0",
"react-dom": "^18.2.0" // ✅ Same major version
}
Why This Matters: react-dom is tightly coupled to React internals. Version mismatch causes runtime errors.
When you update one package, others may need updates too.
Example: Upgrading to React 18
Packages that need updates:
| Package | React 17 Version | React 18 Version | Why |
|---|---|---|---|
react | 17.0.2 | 18.2.0 | Core |
react-dom | 17.0.2 | 18.2.0 | Must match React |
react-router-dom | 5.3.0 | 6.x+ | v6 requires React 18 |
@testing-library/react | 12.x | 13.x+ | Testing hooks for React 18 |
react-scripts | 4.x | 5.x+ | Create React App tooling |
Safe Update Order:
Update all at once (avoid intermediate conflicts):
npm install react@^18.2.0 react-dom@^18.2.0 \
@testing-library/react@^13.0.0 \
react-router-dom@^6.20.0 \
react-scripts@^5.0.1
Check for breaking changes in each package
Run tests after update
Commit dependency updates separately from features
Symptom:
npm install
# Works fine
git pull
npm install
# Suddenly fails with conflicts
Root Cause: package-lock.json is out of sync with package.json
Diagnostic Questions:
package-lock.json committed?package.json without running npm install?npm --version)Fix:
# Delete lock file and regenerate
rm package-lock.json
npm install
# Or update specific package
npm update <package-name>
Version Syntax:
{
"react": "18.2.0", // Exact - only 18.2.0
"react": "^18.2.0", // Caret - 18.x.x (minor/patch updates)
"react": "~18.2.0", // Tilde - 18.2.x (patch updates only)
}
Problem with Exact Versions:
FanHub Standard: Use caret (^) for dependencies
{
"react": "^18.2.0", // ✅ Allows patch and minor updates
"react-router-dom": "^6.20.0" // ✅ Gets security fixes
}
Exception: Exact versions for tools with breaking changes:
{
"typescript": "5.3.3" // Exact - TS has frequent breaking changes
}
Current Stack:
{
"react": "^18.2.0",
"react-dom": "^18.2.0",
"react-router-dom": "^6.20.0",
"@testing-library/react": "^13.4.0",
"react-scripts": "^5.0.1"
}
Key Constraints:
When Upgrading:
Current Stack:
{
"express": "^4.18.2",
"pg": "^8.11.0",
"jest": "^29.5.0"
}
Key Constraints:
When Upgrading:
.nvmrc)When npm install fails:
Read the error message for package names
While resolving: [PACKAGE A]
Found: [PACKAGE B]
peer [VERSION REQUIREMENT] from [PACKAGE A]
Identify the conflict type:
Check current versions:
npm list [package-name]
Find compatible versions:
Plan update order:
Execute and test:
npm install [packages]
npm test
Run before major updates:
node .github/skills/dependency-conflict-resolver/analyze-dependencies.js frontend/package.json
Output Example:
{
"file": "frontend/package.json",
"totalDependencies": 42,
"issues": [
{
"severity": "error",
"package": "react-router-dom",
"message": "react-router-dom@6 requires React 18+, but found React 17",
"fix": "Upgrade react and react-dom to ^18.0.0, or downgrade react-router-dom to ^5.3.0",
"category": "peer-dependency"
},
{
"severity": "warning",
"package": "react, typescript",
"message": "2 packages use exact versions (no ^ or ~)",
"fix": "Consider using ^ for minor version updates: \"^1.2.3\" allows 1.x.x updates",
"category": "versioning-strategy"
}
],
"summary": "Found 2 potential issue(s)"
}
Interpretation:
severity: error — Will cause install failureseverity: warning — May cause issues or is non-optimalcategory — Type of issue (helps with resolution)Before updating:
# View package's changelog
npm view [package-name] repository.url
# Visit repo → CHANGELOG.md
# Or check directly on npm
npm view [package-name] version
npm view [package-name]@latest version
Key breaking changes to check:
Don't do this (causes intermediate conflicts):
npm install react@^18.0.0 # Install
npm install react-dom@^18.0.0 # Conflict with existing lock
npm install @testing-library/react@^13.0.0 # More conflicts
Do this (resolve all at once):
npm install react@^18.0.0 react-dom@^18.0.0 @testing-library/react@^13.0.0
After updating:
# Check what was installed
npm list [package-name]
# Run tests
npm test
# Check for security issues
npm audit
# Separate commits for dependency updates
git add package.json package-lock.json
git commit -m "chore: upgrade React 17 → 18 and related packages
- react: 17.0.2 → 18.2.0
- react-dom: 17.0.2 → 18.2.0
- @testing-library/react: 12.1.5 → 13.4.0
Breaking changes reviewed in React 18 migration guide."
# Then commit feature work
Why: Makes it easy to revert dependency changes if something breaks.
| Error | Likely Cause | Fix |
|---|---|---|
ERESOLVE peer react@18 | Package needs newer React | Upgrade React + ecosystem together |
| React/React-DOM mismatch | Different major versions | Sync both to same major version |
| Lock file conflicts | Desync with package.json | Delete package-lock.json, reinstall |
| "Couldn't find package" | Typo or unpublished version | Check npm registry for correct version |
| Install works, app breaks | Breaking changes in update | Read CHANGELOGs, update code |
Ask Copilot with this skill when:
npm install fails with ERESOLVEExample prompts:
Review an exec-talk's README and produce an exec.recipe.yml. Uses a 3-agent collaborative council to analyze section weighting, executive audience fit, narrative arc, and action clarity. Always overwrites any existing recipe. Triggers: "review the talk", "create the recipe", "is this landing for execs", "section weighting", "coverage gap", "recipe", "executive framing".
Review a tech-talk's README and produce a deck.recipe.yml. Uses a 3-agent collaborative council to analyze section weighting, narrative arc, and coverage gaps. Always overwrites any existing recipe. Triggers: "review the talk", "create the recipe", "is this the best use of our time", "section weighting", "coverage gap", "recipe".
Read from and write to the Workbench project memory store. Use when starting complex content work (query for prior context) or finishing a session that changed content (record drawer entries). Never invoke during agent pre-flight gates.
Add persona-grounded audience framing to a tech-talk. Selects 2–3 relevant personas, adds a "Who This Hits" box and up to 3 reaction lines to the README, and adds persona speaker notes to the slide deck. Triggers: "add personas", "who this hits", "persona reactions", "audience framing".
Use this skill when asked to verify, validate, fact-check, or review any data entry, lore fact, character bio, episode record, quote, or show content for accuracy against canonical project sources and the live database. Triggers on: check data, verify data, fact-check, accuracy check, data accuracy, check entry, verify entry, review accuracy, is this accurate, canon check, lore check, check this data, verify this, review this entry, check for errors, validate data, is this right, is this canon.
Use this skill when asked to verify, validate, or fact-check a lore entry, character description, seed data record, or any Breaking Bad content against the canonical reference in docs/breaking-bad-universe.md. Triggers on: check lore, verify lore, fact-check, canon check, lore accuracy, is this correct, seed data accuracy.