{"kind":"Skill","metadata":{"namespace":"community","name":"react18-dep-compatibility","version":"0.1.0"},"spec":{"description":"React 18.3.1 and React 19 dependency compatibility matrix.","files":{"SKILL.md":"---\nname: react18-dep-compatibility\ndescription: 'React 18.3.1 and React 19 dependency compatibility matrix.'\n---\n\n# React Dependency Compatibility Matrix\n\nMinimum versions required for React 18.3.1 and React 19 compatibility.\n\nUse 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.\n\nReview 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.\n## Core Upgrade Targets\n\n| Package | React 17 (current) | React 18.3.1 (min) | React 19 (min) | Notes |\n|---|---|---|---|---|\n| `react` | 17.x | **18.3.1** | **19.0.0** | Pin exactly to 18.3.1 for the R18 orchestra |\n| `react-dom` | 17.x | **18.3.1** | **19.0.0** | Must match react version exactly |\n\n## Testing Libraries\n\n| Package | React 18 Min | React 19 Min | Notes |\n|---|---|---|---|\n| `@testing-library/react` | **14.0.0** | **16.0.0** | RTL 13 uses ReactDOM.render internally - broken in R18 |\n| `@testing-library/jest-dom` | **6.0.0** | **6.0.0** | v5 works but v6 has React 18 matcher updates |\n| `@testing-library/user-event` | **14.0.0** | **14.0.0** | v13 is sync, v14 is async - API change required |\n| `jest` | **27.x** | **27.x** | jest 27+ with jsdom 16+ for React 18 |\n| `jest-environment-jsdom` | **27.x** | **27.x** | Must match jest version |\n\n## Apollo Client\n\n| Package | React 18 Min | React 19 Min | Notes |\n|---|---|---|---|\n| `@apollo/client` | **3.8.0** | **3.11.0** | 3.8 adds `useSyncExternalStore` for concurrent mode |\n| `graphql` | **15.x** | **16.x** | Apollo 3.8+ peer requires graphql 15 or 16 |\n\nRead **`references/apollo-details.md`** for concurrent mode issues and MockedProvider changes.\n\n## Emotion\n\n| Package | React 18 Min | React 19 Min | Notes |\n|---|---|---|---|\n| `@emotion/react` | **11.10.0** | **11.13.0** | 11.10 adds React 18 concurrent mode support |\n| `@emotion/styled` | **11.10.0** | **11.13.0** | Must match @emotion/react version |\n| `@emotion/cache` | **11.10.0** | **11.13.0** | If used directly |\n\n## React Router\n\n| Package | React 18 Min | React 19 Min | Notes |\n|---|---|---|---|\n| `react-router-dom` | **v6.0.0** | **v6.8.0** | v5 → v6 is a breaking migration - see details below |\n| `react-router-dom` v5 | 5.3.4 (workaround) | ❌ Not supported | See legacy peer deps note |\n\n**react-router v5 → v6 is a SEPARATE migration sprint.** Read `references/router-migration.md`.\n\n## Redux\n\n| Package | React 18 Min | React 19 Min | Notes |\n|---|---|---|---|\n| `react-redux` | **8.0.0** | **9.0.0** | v7 works on R18 legacy root only - breaks on concurrent mode |\n| `redux` | **4.x** | **5.x** | Redux itself is framework-agnostic - react-redux version matters |\n| `@reduxjs/toolkit` | **1.9.0** | **2.0.0** | RTK 1.9 tested against React 18 |\n\n## Other Common Packages\n\n| Package | React 18 Min | React 19 Min | Notes |\n|---|---|---|---|\n| `react-query` / `@tanstack/react-query` | **4.0.0** | **5.0.0** | v3 doesn't support concurrent mode |\n| `react-hook-form` | **7.0.0** | **7.43.0** | v6 has concurrent mode issues |\n| `formik` | **2.2.9** | **2.4.0** | v2.2.9 patched for React 18 |\n| `react-select` | **5.0.0** | **5.8.0** | v4 has peer dep conflicts with R18 |\n| `react-datepicker` | **4.8.0** | **6.0.0** | v4.8+ added React 18 support |\n| `react-dnd` | **16.0.0** | **16.0.0** | v15 and below have R18 concurrent mode issues |\n| `prop-types` | any | any | Standalone - unaffected by React version |\n\n---\n\n## Conflict Resolution Decision Tree\n\n```\nnpm ls shows peer conflict for package X\n         │\n         ▼\nDoes package X have a version that supports React 18?\n  YES → npm install X@[min-compatible-version]\n  NO  ↓\n         │\nIs the package critical to the app?\n  YES → check GitHub issues for React 18 branch/fork\n      → check if maintainer has a PR open\n      → last resort: --legacy-peer-deps (document why)\n  NO  → consider removing the package\n```\n\n## --legacy-peer-deps Rules\n\nOnly use `--legacy-peer-deps` when:\n- The package has no React 18 compatible release\n- The package is actively maintained (not abandoned)\n- The conflict is only a peer dep declaration mismatch (not actual API incompatibility)\n\n**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.\n","references/apollo-details.md":"# Apollo Client - React 18 Compatibility Details\n\n## Why Apollo 3.8+ is Required\n\nApollo 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.\n\nApollo 3.8 was the first version to adopt `useSyncExternalStore`, which React 18 requires for external stores to work correctly under concurrent rendering.\n\n## Version Summary\n\n| Apollo Version | React 18 Support | React 19 Support | Notes |\n|---|---|---|---|\n| \u003c 3.7 | ❌ | ❌ | Concurrent mode data tearing |\n| 3.7.x | ⚠️ | ⚠️ | Works with legacy root only (ReactDOM.render) |\n| **3.8.x** | ✅ | ✅ | First fully compatible version |\n| 3.9+ | ✅ | ✅ | Recommended |\n| 3.11+ | ✅ | ✅ (confirmed) | Explicit React 19 testing added |\n\n## If You're on Apollo 3.7 Using Legacy Root\n\nIf 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.\n\nAs soon as `createRoot` is used, upgrade Apollo to 3.8+.\n\n## MockedProvider in Tests - React 18\n\nApollo's `MockedProvider` works with React 18 but async behavior changed:\n\n```jsx\n// Old pattern - flushing with setTimeout:\nawait new Promise(resolve =\u003e setTimeout(resolve, 0));\nwrapper.update();\n\n// React 18 pattern - use waitFor or findBy:\nawait waitFor(() =\u003e {\n  expect(screen.getByText('Alice')).toBeInTheDocument();\n});\n// OR:\nexpect(await screen.findByText('Alice')).toBeInTheDocument();\n```\n\n## Upgrading Apollo\n\n```bash\nnpm install @apollo/client@latest graphql@latest\n```\n\nIf graphql peer dep conflicts with other packages:\n\n```bash\nnpm ls graphql  # check what version is being used\nnpm info @apollo/client peerDependencies  # check what apollo requires\n```\n\nApollo 3.8+ supports both `graphql@15` and `graphql@16`.\n\n## InMemoryCache - No Changes Required\n\n`InMemoryCache` configuration is unaffected by the React 18 upgrade. No migration needed for:\n\n- `typePolicies`\n- `fragmentMatcher`\n- `possibleTypes`\n- Custom field policies\n\n## useQuery / useMutation / useSubscription - No Changes\n\nApollo hooks are unchanged in their API. The upgrade is entirely internal to how Apollo integrates with React's rendering model.\n","references/router-migration.md":"# React Router v5 → v6 - Scope Assessment\n\n## Why This Is a Separate Sprint\n\nReact Router v5 → v6 is a complete API rewrite. Unlike most React 18 upgrade steps which touch individual patterns, the router migration affects:\n\n- Every `\u003cRoute\u003e` component\n- Every `\u003cSwitch\u003e` (replaced by `\u003cRoutes\u003e`)\n- Every `useHistory()` (replaced by `useNavigate()`)\n- Every `useRouteMatch()` (replaced by `useMatch()`)\n- Every `\u003cRedirect\u003e` (replaced by `\u003cNavigate\u003e`)\n- Nested route definitions (entirely new model)\n- Route parameters access\n- Query string handling\n\nAttempting this as part of the React 18 upgrade sprint will scope-creep the migration significantly.\n\n## Recommended Approach\n\n### Option A - Defer Router Migration (Recommended)\n\nUse `react-router-dom@5.3.4` with `--legacy-peer-deps` during the React 18 upgrade. This is explicitly documented as a supported workaround by the react-router team for React 18 compatibility on legacy root.\n\n```bash\n# In the React 18 dep surgeon:\nnpm install react-router-dom@5.3.4 --legacy-peer-deps\n```\n\nDocument in package.json:\n\n```json\n\"_legacyPeerDepsReason\": {\n  \"react-router-dom@5.3.4\": \"Router v5→v6 migration deferred to separate sprint. React 18 peer dep mismatch only - no API incompatibility on legacy root.\"\n}\n```\n\nThen schedule the v5 → v6 migration as its own sprint after the React 18 upgrade is stable.\n\n### Option B - Migrate Router as Part of React 18 Sprint\n\nOnly choose this if:\n\n- The app has minimal routing (\u003c 10 routes, no nested routes, no complex navigation logic)\n- The team has bandwidth and the sprint timeline allows it\n\n### Scope Assessment Scan\n\nRun this to understand the router migration scope before deciding:\n\n```bash\necho \"=== Route definitions ===\"\ngrep -rn \"\u003cRoute\\|\u003cSwitch\\|\u003cRedirect\" src/ --include=\"*.js\" --include=\"*.jsx\" | grep -v \"\\.test\\.\" | wc -l\n\necho \"=== useHistory calls ===\"\ngrep -rn \"useHistory()\" src/ --include=\"*.js\" --include=\"*.jsx\" | grep -v \"\\.test\\.\" | wc -l\n\necho \"=== useRouteMatch calls ===\"\ngrep -rn \"useRouteMatch()\" src/ --include=\"*.js\" --include=\"*.jsx\" | grep -v \"\\.test\\.\" | wc -l\n\necho \"=== withRouter HOC ===\"\ngrep -rn \"withRouter\" src/ --include=\"*.js\" --include=\"*.jsx\" | grep -v \"\\.test\\.\" | wc -l\n\necho \"=== history.push / history.replace ===\"\ngrep -rn \"history\\.push\\|history\\.replace\\|history\\.go\" src/ --include=\"*.js\" --include=\"*.jsx\" | grep -v \"\\.test\\.\" | wc -l\n```\n\n**Decision guide:**\n\n- Total hits \u003c 30 → router migration is feasible in this sprint\n- Total hits 30–100 → strongly recommend deferring\n- Total hits \u003e 100 → must defer - separate sprint required\n\n## v5 → v6 API Changes Summary\n\n| v5 | v6 | Notes |\n|---|---|---|\n| `\u003cSwitch\u003e` | `\u003cRoutes\u003e` | Direct replacement |\n| `\u003cRoute path=\"/\" component={C}\u003e` | `\u003cRoute path=\"/\" element={\u003cC /\u003e}\u003e` | element prop, not component |\n| `\u003cRoute exact path=\"/\"\u003e` | `\u003cRoute path=\"/\"\u003e` | exact is default in v6 |\n| `\u003cRedirect to=\"/new\"\u003e` | `\u003cNavigate to=\"/new\" /\u003e` | Component rename |\n| `useHistory()` | `useNavigate()` | Returns a function, not an object |\n| `history.push('/path')` | `navigate('/path')` | Direct call |\n| `history.replace('/path')` | `navigate('/path', { replace: true })` | Options object |\n| `useRouteMatch()` | `useMatch()` | Different return shape |\n| `match.params` | `useParams()` | Hook instead of prop |\n| Nested routes inline | Nested routes in config | Layout routes concept |\n| `withRouter` HOC | `useNavigate` / `useParams` hooks | HOC removed |\n"},"import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/tree/541b7819d8c3545c6df122491af4fa1eae415779/plugins/react18-upgrade/skills/react18-dep-compatibility"}},"content_hash":[147,242,30,154,228,220,59,105,225,133,71,0,218,149,186,236,28,201,61,150,218,27,63,9,95,57,20,198,159,4,118,226],"trust_level":"unsigned","yanked":false}