# 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 Version | React 18 Support | React 19 Support | Notes |
|---|---|---|---|
| < 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:

```jsx
// 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

```bash
npm install @apollo/client@latest graphql@latest
```

If graphql peer dep conflicts with other packages:

```bash
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.

# React Router v5 → v6 - Scope Assessment

## Why This Is a Separate Sprint

React Router v5 → v6 is a complete API rewrite. Unlike most React 18 upgrade steps which touch individual patterns, the router migration affects:

- Every `<Route>` component
- Every `<Switch>` (replaced by `<Routes>`)
- Every `useHistory()` (replaced by `useNavigate()`)
- Every `useRouteMatch()` (replaced by `useMatch()`)
- Every `<Redirect>` (replaced by `<Navigate>`)
- Nested route definitions (entirely new model)
- Route parameters access
- Query string handling

Attempting this as part of the React 18 upgrade sprint will scope-creep the migration significantly.

## Recommended Approach

### Option A - Defer Router Migration (Recommended)

Use `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.

```bash
# In the React 18 dep surgeon:
npm install react-router-dom@5.3.4 --legacy-peer-deps
```

Document in package.json:

```json
"_legacyPeerDepsReason": {
  "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."
}
```

Then schedule the v5 → v6 migration as its own sprint after the React 18 upgrade is stable.

### Option B - Migrate Router as Part of React 18 Sprint

Only choose this if:

- The app has minimal routing (< 10 routes, no nested routes, no complex navigation logic)
- The team has bandwidth and the sprint timeline allows it

### Scope Assessment Scan

Run this to understand the router migration scope before deciding:

```bash
echo "=== Route definitions ==="
grep -rn "<Route\|<Switch\|<Redirect" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l

echo "=== useHistory calls ==="
grep -rn "useHistory()" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l

echo "=== useRouteMatch calls ==="
grep -rn "useRouteMatch()" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l

echo "=== withRouter HOC ==="
grep -rn "withRouter" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l

echo "=== history.push / history.replace ==="
grep -rn "history\.push\|history\.replace\|history\.go" src/ --include="*.js" --include="*.jsx" | grep -v "\.test\." | wc -l
```

**Decision guide:**

- Total hits < 30 → router migration is feasible in this sprint
- Total hits 30–100 → strongly recommend deferring
- Total hits > 100 → must defer - separate sprint required

## v5 → v6 API Changes Summary

| v5 | v6 | Notes |
|---|---|---|
| `<Switch>` | `<Routes>` | Direct replacement |
| `<Route path="/" component={C}>` | `<Route path="/" element={<C />}>` | element prop, not component |
| `<Route exact path="/">` | `<Route path="/">` | exact is default in v6 |
| `<Redirect to="/new">` | `<Navigate to="/new" />` | Component rename |
| `useHistory()` | `useNavigate()` | Returns a function, not an object |
| `history.push('/path')` | `navigate('/path')` | Direct call |
| `history.replace('/path')` | `navigate('/path', { replace: true })` | Options object |
| `useRouteMatch()` | `useMatch()` | Different return shape |
| `match.params` | `useParams()` | Hook instead of prop |
| Nested routes inline | Nested routes in config | Layout routes concept |
| `withRouter` HOC | `useNavigate` / `useParams` hooks | HOC removed |