AutoGineer
Generated banner for React18 Dep Compatibility
Generated logo for React18 Dep Compatibility

React18 Dep Compatibility

GitHubOfficialFirst committed by SaravananRajaramanDistributed by GitHub

  • Skill
  • Guidelines
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

React 18.3.1 and React 19 dependency compatibility matrix.
— the description by SaravananRajaraman

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured reference for managing dependency compatibility during React 18.3.1 and React 19 upgrades. It includes a comprehensive compatibility matrix for common libraries like Apollo Client, Emotion, React Router, and testing utilities, alongside a decision tree for resolving peer dependency conflicts and guidelines for the safe use of --legacy-peer-deps.

What it does

  • Provides minimum version requirements for React 18.3.1 and 19 compatibility.
  • Offers a decision tree for resolving npm peer dependency conflicts.
  • Details specific migration considerations for Apollo Client and React Router.
  • Defines strict rules for when and how to document the use of --legacy-peer-deps.
  • Summarizes breaking changes and necessary updates for testing libraries.
  • Helps assess the scope of complex migrations like React Router v5 to v6.

When to use it

  • Before initiating a React upgrade to version 18.3.1 or 19.
  • When encountering npm peer dependency conflicts during package installation.
  • When deciding whether to defer a major library migration, such as React Router.
  • When assessing the risk of concurrent mode compatibility issues.
  • Before accepting a dependency resolution that might require --legacy-peer-deps.

Advantages

  • Reduces the risk of runtime errors caused by incompatible dependency versions.
  • Provides a clear, standardized process for handling peer dependency conflicts.
  • Prevents scope creep by identifying migrations that should be handled in separate sprints.
  • Ensures consistent documentation practices for legacy dependency workarounds.
  • Centralizes critical compatibility data for common React ecosystem tools.

Usage examples

“What is the minimum version of @apollo/client required for React 18?”
The skill identifies that @apollo/client 3.8.0 is the minimum version required to support React 18 concurrent mode.
“Should I upgrade React Router to v6 during my React 18 migration?”
The skill advises that React Router v5 to v6 is a major API rewrite and recommends deferring it to a separate sprint unless the project scope is very small.
“How do I handle a peer dependency conflict for a package that doesn't support React 18 yet?”
The skill provides a decision tree to check if the package is critical, search for existing PRs, and only use --legacy-peer-deps as a last resort with proper documentation.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/github/react18-dep-compatibility/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip react18-dep-compatibility.zip -d .agents/skills

Documentation by SaravananRajaraman

React Dependency Compatibility Matrix

Minimum versions required for React 18.3.1 and React 19 compatibility.

Use this skill whenever checking whether a dependency supports a target React version, resolving peer dependency conflicts, deciding whether to upgrade or use legacy-peer-deps, or assessing the risk of a react-router v5 to v6 migration.

Review this matrix before running npm install during a React upgrade and before accepting an npm dependency conflict resolution, especially where concurrent mode compatibility may be affected.

Core Upgrade Targets

PackageReact 17 (current)React 18.3.1 (min)React 19 (min)Notes
react17.x18.3.119.0.0Pin exactly to 18.3.1 for the R18 orchestra
react-dom17.x18.3.119.0.0Must match react version exactly

Testing Libraries

PackageReact 18 MinReact 19 MinNotes
@testing-library/react14.0.016.0.0RTL 13 uses ReactDOM.render internally - broken in R18
@testing-library/jest-dom6.0.06.0.0v5 works but v6 has React 18 matcher updates
@testing-library/user-event14.0.014.0.0v13 is sync, v14 is async - API change required
jest27.x27.xjest 27+ with jsdom 16+ for React 18
jest-environment-jsdom27.x27.xMust match jest version

Apollo Client

PackageReact 18 MinReact 19 MinNotes
@apollo/client3.8.03.11.03.8 adds useSyncExternalStore for concurrent mode
graphql15.x16.xApollo 3.8+ peer requires graphql 15 or 16

Read references/apollo-details.md for concurrent mode issues and MockedProvider changes.

Emotion

PackageReact 18 MinReact 19 MinNotes
@emotion/react11.10.011.13.011.10 adds React 18 concurrent mode support
@emotion/styled11.10.011.13.0Must match @emotion/react version
@emotion/cache11.10.011.13.0If used directly

React Router

PackageReact 18 MinReact 19 MinNotes
react-router-domv6.0.0v6.8.0v5 → v6 is a breaking migration - see details below
react-router-dom v55.3.4 (workaround)❌ Not supportedSee legacy peer deps note

react-router v5 → v6 is a SEPARATE migration sprint. Read references/router-migration.md.

Redux

PackageReact 18 MinReact 19 MinNotes
react-redux8.0.09.0.0v7 works on R18 legacy root only - breaks on concurrent mode
redux4.x5.xRedux itself is framework-agnostic - react-redux version matters
@reduxjs/toolkit1.9.02.0.0RTK 1.9 tested against React 18

Other Common Packages

PackageReact 18 MinReact 19 MinNotes
react-query / @tanstack/react-query4.0.05.0.0v3 doesn't support concurrent mode
react-hook-form7.0.07.43.0v6 has concurrent mode issues
formik2.2.92.4.0v2.2.9 patched for React 18
react-select5.0.05.8.0v4 has peer dep conflicts with R18
react-datepicker4.8.06.0.0v4.8+ added React 18 support
react-dnd16.0.016.0.0v15 and below have R18 concurrent mode issues
prop-typesanyanyStandalone - unaffected by React version

Conflict Resolution Decision Tree

npm ls shows peer conflict for package X
         │
         ▼
Does package X have a version that supports React 18?
  YES → npm install X@[min-compatible-version]
  NO  ↓
         │
Is the package critical to the app?
  YES → check GitHub issues for React 18 branch/fork
      → check if maintainer has a PR open
      → last resort: --legacy-peer-deps (document why)
  NO  → consider removing the package

--legacy-peer-deps Rules

Only use --legacy-peer-deps when:

  • The package has no React 18 compatible release

  • The package is actively maintained (not abandoned)

  • The conflict is only a peer dep declaration mismatch (not actual API incompatibility)

Document every --legacy-peer-deps usage in a comment at the top of package.json or in a MIGRATION.md file explaining why it was necessary.

Files

references/apollo-details.md

Apollo Client - React 18 Compatibility Details

Why Apollo 3.8+ is Required

Apollo Client 3.7 and below use an internal subscription model that is not compatible with React 18's concurrent rendering. In concurrent mode, React can interrupt and replay renders, which causes Apollo's store subscriptions to fire at incorrect times - producing stale data or missed updates.

Apollo 3.8 was the first version to adopt useSyncExternalStore, which React 18 requires for external stores to work correctly under concurrent rendering.

Version Summary

Apollo VersionReact 18 SupportReact 19 SupportNotes
< 3.7❌❌Concurrent mode data tearing
3.7.x⚠️⚠️Works with legacy root only (ReactDOM.render)
3.8.x✅✅First fully compatible version
3.9+✅✅Recommended
3.11+✅✅ (confirmed)Explicit React 19 testing added

If You're on Apollo 3.7 Using Legacy Root

If the app still uses ReactDOM.render (legacy root) and hasn't migrated to createRoot yet, Apollo 3.7 will technically work - but this means you're not getting any React 18 concurrent features (including automatic batching). This is a partial upgrade only.

As soon as createRoot is used, upgrade Apollo to 3.8+.

MockedProvider in Tests - React 18

Apollo's MockedProvider works with React 18 but async behavior changed:

// Old pattern - flushing with setTimeout:
await new Promise(resolve => setTimeout(resolve, 0));
wrapper.update();

// React 18 pattern - use waitFor or findBy:
await waitFor(() => {
  expect(screen.getByText('Alice')).toBeInTheDocument();
});
// OR:
expect(await screen.findByText('Alice')).toBeInTheDocument();

Upgrading Apollo

npm install @apollo/client@latest graphql@latest

If graphql peer dep conflicts with other packages:

npm ls graphql  # check what version is being used
npm info @apollo/client peerDependencies  # check what apollo requires

Apollo 3.8+ supports both graphql@15 and graphql@16.

InMemoryCache - No Changes Required

InMemoryCache configuration is unaffected by the React 18 upgrade. No migration needed for:

  • typePolicies

  • fragmentMatcher

  • possibleTypes

  • Custom field policies

useQuery / useMutation / useSubscription - No Changes

Apollo hooks are unchanged in their API. The upgrade is entirely internal to how Apollo integrates with React's rendering model.

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

First committed by
GitHub avatar of SaravananRajaramanSaravananRajaraman
Publisher
GitHub (Official)
Distributed by
GitHub
Source
github/awesome-copilot · skills/react18-dep-compatibility · commit 797337f
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
SaravananRajaraman

AutoGineer is not affiliated with or endorsed by SaravananRajaraman or GitHub.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download react18-dep-compatibility.zip