←Back to use cases
Migrations

Create a React 18 to 19 Upgrade Playbook

Turn the official React 19 upgrade guide into a phased playbook mapped to your codebase.

Advanced CapabilitiesPlaybooks
AuthorOpulent
CategoryMigrations
FeaturesAdvanced Capabilities, Playbooks
start it with one message
Read the React 19 upgrade guide and our React app. Build a migration playbook that maps every breaking change to our code, which files use removed APIs, what needs the new JSX transform, and how to phase the upgrade so we can ship incrementally.
Run this in OpulentCopy it, swap the names for your own, and send it.
connected systems
GitHubManage repositories, track code changes, and collaborate on team projects
LinearTrack issues, manage projects, and organize workflows across your team
VercelManage Vercel projects, deployments, and domains
step 1

Feed the upgrade guide and codebase to Opulent

Connect GitHub so Opulent can read the repo. Give Opulent the URL to the official React 19 upgrade guide and any dependency-specific migration guides (React Router, React Hook Form, your UI library). Opulent reads the guides and cross-references them against your actual files.

The output is a codebase-specific playbook, a reusable, named set of steps that maps every breaking change to the files that need to change.

Prompt to Opulent:

We're upgrading from React 18 to React 19. Here's the guide:
https://react.dev/blog/2024/04/25/react-19-upgrade-guide

Build a migration playbook for our codebase:
1. Install react@18.3 first and fix every deprecation warning.
2. Find all uses of forwardRef and plan the ref-as-prop migration.
3. Identify legacy Context API usage (contextTypes, getChildContext)
   that needs conversion to createContext.
4. Flag string refs and legacy lifecycle methods.
5. List TypeScript files that need updated ref types.
6. Order the steps so we can ship incrementally.
7. Include a validation step after each phase.
Tip

Tell Opulent about your codebase-specific patterns: 'we have 23 forwardRef components under src/components/ui/' or 'we still have 4 class components in src/legacy/.' This turns a generic guide into a concrete file list.

step 2

Review the phased playbook

Opulent returns a playbook with phases, estimated complexity, and specific files. Each phase should be shippable on its own, so the team can merge deprecation fixes before touching API removals.

Validate the playbook against a staging deployment on Vercel before the first phase merges to production.

# React 18 -> 19 Migration Playbook

## Phase 1: Upgrade to React 18.3 and fix deprecation warnings (S)
- npm install react@18.3 react-dom@18.3
- Remove string refs in src/legacy/OldModal.tsx,
  src/legacy/OldTooltip.tsx.
- Replace ReactDOM.findDOMNode in src/legacy/DropdownMenu.tsx.
- Validation: zero deprecation warnings, all tests pass.

## Phase 2: Migrate forwardRef to ref-as-prop (M)
- Remove forwardRef wrappers from 23 components in src/components/ui/.
- Pass ref as a regular prop.
- Update TypeScript types: RefObject<T> -> RefObject<T> | null.
- Validation: focus management works, all ref tests pass.

## Phase 3: Remove deprecated APIs (M)
- Convert legacy Context in src/legacy/LocaleContext.tsx.
- Remove propTypes from 12 files.
- Remove defaultProps from function components.
- Validation: app renders, context values propagate.

## Phase 4: Adopt React 19 (L)
- npm install react@19 react-dom@19.
- Use new APIs where beneficial (async actions, use() for promises).
- Validation: full test suite and E2E pass.
step 3

Run each phase as a separate work package

Start one Opulent run per phase. Each run applies the phase's changes, runs the validation steps, and opens a PR. Because the phases are ordered, you merge Phase 1 before starting Phase 2.

If a phase touches many files, split it into parallel packages that do not modify the same files. Use the same grouping logic as Migrate 50 Files from REST to GraphQL.

step 4

Validate and deploy incrementally

After each phase merges, deploy to a Vercel preview and run the test suite. If the preview passes, promote to production. If it fails, the scope is small enough to roll back or patch quickly.

Incremental validation is the safeguard: a big-bang React upgrade is risky because many failures appear at once; phased merges surface one class of problem at a time.

step 5

Sharpen the upgrade playbook

When Opulent finds a breaking change not covered by the guide, add it to the playbook or write it into memory (the notes a run recalls next time). Update the validation steps as the app changes.

Re-use the same phased pattern for other framework upgrades (TypeScript, Next.js, Tailwind) by swapping the guide URL and the phase mappings.

The natural chain: when the upgrade reveals bugs, use Debug a Bug Report End-to-End; when it requires visual regression checks, use Catch Visual Regressions Before Every PR; when many files need the same change, use Fleet-Wide Maintenance Across Thousands of Repositories.