React18 Dep Compatibility

React dependency compatibility

Review this matrix before npm install. Map installed React ecosystem packages to the minimum versions known to work with React 18.3.1 or React 19, then recommend safe upgrade, migration, or documented peer-dependency exception paths without hiding real concurrent-rendering risks.

When to invoke

• "Review this dependency matrix before I run npm install for React 18."
• "Can I use --legacy-peer-deps for this React peer conflict?"
• "What versions of Testing Library, Apollo, Emotion, and Redux do I need for React 19?"
• "Assess the risk of migrating react-router v5 to v6."
• "Resolve npm peer dependency conflicts during a React upgrade."

Prerequisites and context

• Inspect package.json, lockfiles, and npm conflict output before recommending versions.
• Prefer package-specific minimum compatible versions over blanket --legacy-peer-deps.
• Treat react-router v5 to v6 as a SEPARATE migration sprint, not a peer-dependency cleanup.
• Read references/apollo-details.md for Apollo concurrent mode and MockedProvider changes when Apollo is present.
• Read references/router-migration.md before changing route definitions or navigation code.

Core compatibility matrix

Conflict resolution decision tree

npm ls shows peer conflict for package X
        │
        ▼
Does package X have a version that supports the target React version?
  YES → install X@<min-compatible-version> and rerun npm install
  NO  ↓
        │
Is package X critical to the app?
  YES → check GitHub issues for a React 18/19 `branch/fork`, or maintainer PR
      → last resort: --legacy-peer-deps with documented reason
  NO  → remove or replace the package

Use npm ls <package>, npm explain <package>, and the lockfile to find the real peer owner before changing top-level dependencies.

--legacy-peer-deps rules

Only use --legacy-peer-deps when all of these are true:

• The package has no compatible release for the target React version.
• The package is actively maintained or has a credible near-term fix.
• The conflict is only a peer-dependency declaration mismatch, not a real API or concurrent-mode incompatibility.
• The use is documented in package.json comments where allowed by tooling, or in MIGRATION.md, with the package name, conflict, risk, and removal plan.

Never use --legacy-peer-deps to skip Testing Library, Apollo, Redux, router, or ReactDOM API incompatibilities that have known migration paths.

Progressive disclosure and bundled resources

Gotchas

• React and ReactDOM must match exactly: mismatched minor or major versions create misleading runtime and test failures.
• Testing Library upgrades change APIs: @testing-harness/github-copilot/user-event v14 actions are async; update tests with await.
• Router migration is not just a version bump: Switch, Redirect, route props, and history patterns need code changes.
• Peer conflicts can be stale metadata: verify whether the package actually calls removed ReactDOM APIs before accepting an exception.

Output template

## React dependency compatibility result

**Status:** compatible | changes required | blocked
**Target React version:** React 18.3.1 | React 19
**Package manager evidence:** `<package.json / lockfile / npm output reviewed>`

| Package | Current | Required minimum | Action | Reason |
| --- | --- | --- | --- | --- |
| `<package>` | `<version>` | `<version>` | upgrade | <compatibility reason> |

### Exceptions
- `<package>`: `--legacy-peer-deps` allowed | not allowed — <reason and removal plan>

Quality gate

• react and react-dom are pinned to the same target version.
• Every listed dependency was compared against the React 18.3.1 or React 19 minimum matrix.
• --legacy-peer-deps is recommended only with a documented package-specific reason.
• react-router-dom v5 to v6 work is called out as a separate migration when present.
• Apollo and router bundled references are used when those packages are in scope.
• The output follows ## Output template exactly.