> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# React 19 Migration Brief (Context7-backed)

> Source: Context7 libraries /reactjs/react.dev, /facebook/react. Use: Embed as "Research Brief" in PF-76 spec.

**Source:** Context7 libraries `/reactjs/react.dev`, `/facebook/react`.\
**Use:** Embed as "Research Brief" in PF-76 spec.

***

## Official upgrade path and prerequisites

* **Upgrade to React 18.3 first.** React 18.3 adds warnings for deprecated APIs and aligns behavior needed for React 19. (Ref: [React 19 Upgrade Guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide), React 18.3 release notes in [CHANGELOG](https://github.com/facebook/react/blob/main/CHANGELOG.md#1830-april-25-2024).)
* **This repo:** Already on `react@^18.3.1`, `react-dom@^18.3.1`; `src/main.tsx` uses `createRoot` from `react-dom/client`. No legacy `ReactDOM.render` or `hydrate` in app code.

***

## Confirmed breaking / removed APIs

| API                               | Status              | Migration                                                     |
| --------------------------------- | ------------------- | ------------------------------------------------------------- |
| `ReactDOM.render`                 | Removed in React 19 | Use `createRoot` from `react-dom/client` (already in use).    |
| `ReactDOM.hydrate`                | Removed in React 19 | Use `hydrateRoot` from `react-dom/client` if SSR.             |
| `act` from `react-dom/test-utils` | Moved/removed       | Import `act` from `react`. Other test-utils removed.          |
| String refs                       | Deprecated/removed  | Use ref callbacks or `useRef`. Codemod: `replace-string-ref`. |

***

## Required codemods and tools

* **Full migration recipe:**\
  `npx codemod@latest react/19/migration-recipe`\
  (Runs replace-reactdom-render, replace-string-ref, replace-act-import, etc.)
* **Individual codemods:**
  * `npx codemod@latest react/19/replace-reactdom-render` — render/hydrate → createRoot/hydrateRoot
  * `npx codemod@latest react/19/replace-act-import` — act from react-dom/test-utils → react
  * `npx codemod@latest react/19/replace-string-ref` — string refs → callback refs

***

## Repo compatibility notes

* **Entry:** `src/main.tsx` already uses `createRoot`; no change needed for root API.
* **Tests:** Use `@testing-library/react`; `act` is typically used via Testing Library. Verify no direct `import { act } from 'react-dom/test-utils'`; if any, switch to `import { act } from 'react'` or rely on RTL's built-in act.
* **Peers to verify before/after bump:**\
  `react-dropzone`, `teller-connect-react` (transitive react-script-hook), `@xyflow/react`, `@tiptap/react`, `react-pdf`, `react-plaid-link`, `react-router-dom`, `@radix-ui/*`, `next-themes`, `recharts`, `vaul`.\
  Run `npm install` after bump and fix peer warnings; smoke-test Plaid, PDF viewer, and route-heavy flows.
* **React Compiler:** If adopted later, some third-party APIs may be "known incompatible" and skip memoization; document and test.

***

## Recommended rollout and rollback

1. **Pre-step:** Ensure 18.3.x latest patch; run `npx codemod@latest react/19/migration-recipe` in dry-run or with review.
2. **Bump:** Upgrade `react`, `react-dom`, `@types/react`, `@types/react-dom` to 19.x; `npm install`.
3. **Fix:** Resolve type and peer issues; replace any remaining `react-dom/test-utils` act usage.
4. **Validate:** `npm run validate` and `npm run test:baseline`; manual smoke of Plaid, PDF, navigation.
5. **Rollback:** Revert package.json and lockfile to 18.3.x; re-run `npm install` and full validate.