Migrate React 18 to React 19 Without Losing Your Sanity

Before You Break Everything: What Actually Needs Checking

Look, React 19 isn't some magical upgrade that just works. The official migration guide makes it sound like a pleasant afternoon with a cup of tea, but you're going to spend your weekend debugging TypeScript errors that make no sense and wondering why you didn't become a plumber instead.

Check If Your App Is Gonna Break

First, upgrade to React 18.3 - it adds warnings for stuff that'll explode in React 19. Yeah, it's an extra step, but trust me on this one. I learned this the hard way after spending 3 hours wondering why my modals stopped working.

Node.js bullshit to deal with:

• You need Node 16+ minimum (18+ if you want to avoid weird errors)
• If you're still on Node 14, upgrade that first or you'll hate your life
• TypeScript 4.7+ - older versions will throw fits about useRef changes

Dependencies That Will Definitely Break

React 19 cracked down hard on libraries that were hacking React internals. If you're using any of these, budget extra time:

Libraries that always cause problems:

• React Router - needs v6.8+ or your routing dies
• Styled Components - v5.3.6+ or prepare for ref forwarding hell
• Redux Toolkit - older versions choke on concurrent rendering
• Emotion - check your version or CSS-in-JS will break
• Formik - notorious for using React internals, check latest version
• React Hook Form - usually fine, but verify compatibility

Run npm ls and pray none of your dependencies are using SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED. Yes, that's a real fucking API name. React devs have a sense of humor, we have headaches.

JSX Transform: The Thing Everyone Forgets

React 19 requires the new JSX transform. Been around since 2020, but half of you probably never enabled it. You'll know if you forgot because React will politely tell you:

Your app is using an outdated JSX transform. Update to the modern JSX transform for faster performance

Fix it in your bundler config:

// Webpack/Babel users
{
  "presets": [
    ["@babel/preset-react", { "runtime": "automatic" }]
  ]
}

// Vite users (you lucky bastards)
export default {
  esbuild: {
    jsx: 'automatic'  
  }
}

// Next.js users
// Nothing to do - it's been automatic since v11

Backup Your Shit

I'm serious about this. Create a git branch, backup your database if you're using React Server Components, and test everything in staging first.

Don't be the engineer who YOLOs a React upgrade to production on Friday afternoon. Set up a proper staging environment that matches your production setup.

Time reality check: Plan for 1-2 days of prep work, which in real developer time means 3-4 days because you'll find weird edge cases in your Webpack config, discover your CI is running Node 14, and spend an hour figuring out why your Docker build is failing.

Pro tip: If you're on Webpack 4, just don't. Seriously. Upgrade to Webpack 5 first or you'll spend a week debugging module resolution errors that make zero sense. Trust me, I've been there.

And yeah, you're gonna have questions. Everyone does.

Additional resources: React DevTools, Bundle Analyzer, React 19 FAQ, TypeScript Migration Guide, Vite Migration Guide.

The Actual Migration Steps (Not the Marketing Version)

Here's how to upgrade without crying. The React team's codemods handle 80% of this shit automatically. The other 20% is where you earn your paycheck.

Step 1: Update React (The Easy Part)

Install the damn thing:

npm install --save-exact react@^19.1.1 react-dom@^19.1.1

## TypeScript users get the joy of additional types
npm install --save-exact @types/react@^19.0.0 @types/react-dom@^19.0.0

## Yarn users (you do you)
yarn add --exact react@^19.1.1 react-dom@^19.1.1

Use --save-exact because you don't want surprise patch versions breaking your shit.

Pro tip: React 19.1.1 (July 2025) includes stability fixes for Owner Stacks and improved Suspense handling. If you're still on 19.0.0, update to 19.1.1 unless you enjoy debugging mysterious Suspense issues at 3am.

Step 2: Run the Magic Codemods (Pray They Work)

The React codemods are surprisingly good. Run this and watch your code transform:

npx codemod@latest react/19/migration-recipe

What this actually does:

• replace-reactdom-render: Kills ReactDOM.render (finally)
• replace-string-ref: Converts string refs (you shouldn't have these anyway)
• replace-act-import: Fixes act imports that moved packages
• replace-use-form-state: Updates to the new Actions API
• prop-types-typescript: Removes PropTypes (use TypeScript like an adult)

Pro tip: Commit before running this. When it inevitably breaks something, you'll want to rollback and fix it manually.

Step 3: Deal with TypeScript Carnage

TypeScript users, buckle up. React 19 made the type system stricter, which is great for safety but terrible for your afternoon:

npx types-react-codemod@latest preset-19 ./src

Manual fixes you'll definitely need:

useRef stopped being lazy about arguments:

// Before - TypeScript was chill
const ref = useRef(); // ❌ Now throws errors

// After - Be explicit, goddammit  
const ref = useRef<HTMLDivElement>(null); // ✅
const inputRef = useRef<HTMLInputElement>(null); // ✅

Ref callbacks got pickier:

// Before - worked by accident
<div ref={current => (instance = current)} /> // ❌

// After - explicit is better
<div ref={current => {instance = current}} /> // ✅

Step 4: Replace the Deprecated Crap

ReactDOM.render is dead, long live createRoot:

// Before (React 18 and earlier)
import { render, unmountComponentAtNode } from 'react-dom';
render(<App />, container);
unmountComponentAtNode(container);

// After (React 19 and your new reality)
import { createRoot } from 'react-dom/client';
const root = createRoot(container);
root.render(<App />);
root.unmount();

PropTypes on function components are ignored now:

// Before - worked but was annoying
function Button({ label = 'Click me', onClick }) {
  return <button onClick={onClick}>{label}</button>;
}
Button.propTypes = {
  label: PropTypes.string,
  onClick: PropTypes.func.isRequired
}; // ❌ React 19 ignores this

// After - TypeScript or GTFO
interface ButtonProps {
  label?: string;
  onClick: () => void;
}
function Button({ label = 'Click me', onClick }: ButtonProps) {
  return <button onClick={onClick}>{label}</button>;
} // ✅

Step 5: Fix Your Broken Tests

Your tests are broken. Accept it and move on:

npm test  # Watch it burn

Common failures:

• act import moved: Change import { act } from 'react-dom/test-utils' to import { act } from 'react'
• react-test-renderer is deprecated: Use `@testing-library/react` instead
• Hydration warnings changed: React 19 shows better error messages, so your error assertions might fail

Step 6: Test the New Stuff (Make Sure It Works)

React 19's Actions API is actually pretty neat. Test it doesn't explode:

function TestForm() {
  const [result, action, isPending] = useActionState(async (prev, formData) => {
    // This replaces your useState + async handler pattern
    await new Promise(resolve => setTimeout(resolve, 1000));
    return { success: true, message: 'Form submitted!' };
  }, null);

  return (
    <form action={action}>
      <input name=\"email\" type=\"email\" required />
      <button disabled={isPending}>
        {isPending ? 'Submitting...' : 'Submit'}
      </button>
      {result?.success && <p>{result.message}</p>}
    </form>
  );
}

Turn on Strict Mode and see what breaks:

// This will catch remaining issues
<React.StrictMode>
  <App />
</React.StrictMode>

And if you're one of those teams still using JavaScript without TypeScript in 2025... well, React 19 will remind you why that was a bad choice. The number of runtime errors you'll get from missing prop types will make you want to rewrite everything in TypeScript anyway.

Reality check: The codemods work great until they don't. Budget 2-4 hours if everything goes perfectly, 1-2 days when reality hits and you discover your app was using three different versions of React somehow.

OK, step-by-step stuff covered. Now let's see what actually changed.

Useful links: React 19 Changelog, Migration Codemods, TypeScript React Types, Testing Library Migration Guide, Vite React Plugin, Next.js React 19 Support.

The codemods handle the obvious stuff, but you'll still spend hours fixing the weird edge cases they miss. Here's what actually breaks and how to fix it without losing your mind.

Third-Party Dependencies Are Broken As Hell

Your app will explode with errors like:

• Cannot read properties of undefined
• X is not a function
• Module not found: Can't resolve 'react-dom/client'

Why this happens: Some genius library authors decided to hack React internals (SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED - yes, that's the actual API name). React 19 said "fuck that noise" and broke them all.

How to find the culprits:

## This will show you which libraries are being assholes
npm ls react
grep -r \"SECRET_INTERNALS\" node_modules/*/  # Find the guilty parties

Temporary workaround (buy yourself time):

// package.json - Pin broken libraries to React 18
{
  \"overrides\": {
    \"some-broken-library\": {
      \"react\": \"^18.3.0\"
    },
    \"react-beautiful-dnd\": {  // Notorious for this
      \"react\": \"^18.3.0\"
    }
  }
}

Real solution: Update the libraries or find alternatives that aren't garbage. Check React 19 compatibility lists before upgrading.

TypeScript Will Find New Ways to Hate You

useRef suddenly became a type nazi:

// Before - TypeScript didn't care
const ref = useRef(); // ❌ Now: \"Expected 1 argument but got 0\"

// After - Be explicit about everything
const divRef = useRef<HTMLDivElement>(null);
const inputRef = useRef<HTMLInputElement>(null);
const buttonRef = useRef<HTMLButtonElement>(null);

Ref callbacks got pickier about return types:

// This used to work
<div ref={current => (instance = current)} /> // ❌ Type error

// Now you need explicit assignments
<div ref={current => {instance = current}} /> // ✅

JSX element access is now typed stricter:

// Before - worked by accident  
const element = <MyComponent />;
console.log(element.props.children); // ❌ 'props' doesn't exist

// After - explicit typing or don't access props directly
const element: ReactElement<MyComponentProps> = <MyComponent />;
// Or just don't do this - it's usually a code smell anyway

Pro tip: Run `npx types-react-codemod@latest preset-19 ./src` to fix 90% of this automatically.

Your Tests Are Fucked

Every React upgrade breaks tests. It's tradition.

act() import moved packages:

// Before - worked in React 18
import { act } from 'react-dom/test-utils'; // ❌ Module not found

// After - moved to main React package  
import { act } from 'react'; // ✅

react-test-renderer is deprecated (finally):

// Before - shallow rendering was a thing
import { shallow } from 'enzyme';
const wrapper = shallow(<Component />);

// After - use Testing Library like you should have been doing
import { render, screen } from '@testing-library/react';
render(<Component />);
expect(screen.getByText('Hello')).toBeInTheDocument();

Hydration error messages changed: React 19 shows better diffs, so your error assertions might fail if you were checking for specific error text.

Forms Break In Mysterious Ways

React 19's Actions API is actually good, but it conflicts with the manual form state management everyone's been doing. We YOLOed a React 19 upgrade to staging and our entire form system died like it got hit by a truck. Took 6 hours of debugging and way too much coffee to figure out we were mixing useActionState with manual pending state management:

This pattern will cause weird issues:

// Don't do this anymore - Actions API conflicts
function Form() {
  const [pending, setPending] = useState(false);
  
  const handleSubmit = async (e) => {
    e.preventDefault();
    setPending(true); // This fights with useActionState
    await submitData();
    setPending(false);
  };
}

// Use the new pattern consistently
function Form() {
  const [result, submitAction, isPending] = useActionState(async (prev, formData) => {
    return await submitData(formData); // Just return the result
  }, null);
  
  return (
    <form action={submitAction}>
      <button disabled={isPending}>
        {isPending ? 'Submitting...' : 'Submit'}
      </button>
    </form>
  );
}

Performance Actually Gets Worse (Temporarily)

Strict Mode behavior changed. If you have side effects in render functions, React 19 will punish you harder:

This will cause performance issues in Strict Mode:

// Don't put side effects in render
function BadComponent() {
  localStorage.setItem('key', 'value'); // ❌ Side effect in render
  return <div>Content</div>;
}

// Fix: Move to useEffect
function GoodComponent() {
  useEffect(() => {
    localStorage.setItem('key', 'value'); // ✅ Side effect in effect
  }, []);
  return <div>Content</div>;
}

SSR Hydration Errors You Never Knew Existed

React 19 improved hydration error messages, which is great but also reveals issues that were silently broken before:

Common newly-visible issues:

• Date/time rendering differences between server and client
• Missing suppressHydrationWarning on dynamic content
• Client-only libraries running during SSR

The fix is usually adding proper guards:

function MyComponent() {
  const [isClient, setIsClient] = useState(false);
  
  useEffect(() => {
    setIsClient(true);
  }, []);
  
  return (
    <div>
      {isClient ? <ClientOnlyComponent /> : <div>Loading...</div>}
    </div>
  );
}

Reality check: Most migration issues aren't showstoppers, just annoying. Budget extra time for fixing tests (they always break), updating types (TypeScript got pickier), and hunting down the one library that's using React internals.

Oh, and another thing - if your app loads but forms submit twice, you've got Actions API conflicts with manual form handling. Learned that one the hard way too.

Additional debugging resources: React DevTools Profiler, Why Did You Render, React 19 Breaking Changes List, TypeScript React Cheatsheet, Testing Library Docs, Webpack Bundle Analyzer, Next.js Upgrade Guide, Vite Migration Guide.