How to Upgrade React Version in an Existing Project (Step-by-Step Guide)

Upgrading the React version in an existing project can feel risky, especially if your application is already in production. However, with the right approach, upgrading React is safe, predictable, and often brings performance improvements, bug fixes, and access to modern features.

This article explains how to upgrade React step by step, why each step matters, and how to avoid common mistakes.

---

Why Upgrade React?

Keeping React up to date gives you:

• ⚡ Performance improvements
• 🛠 Bug fixes and security patches
• 🚀 Access to new APIs and features
• 📦 Better compatibility with modern tools (Vite, Next.js, libraries)

---

Check Your Current React Version

Before upgrading, confirm which version you’re using:

npm list react react-dom

Or check package.json:

"react": "^18.2.0",
"react-dom": "^18.2.0"

---

Typical Existing Project Structure

my-react-app/
├── package.json
├── package-lock.json
├── node_modules/
├── public/
└── src/
    ├── App.jsx
    ├── main.jsx
    └── index.css

---

Step 1: Read the Official React Changelog (Important)

Before upgrading across major versions, review breaking changes:

• React 16 → 17: Minimal breaking changes
• React 17 → 18: New root API, concurrent features
• React 18 → Future versions: Gradual improvements

This helps you prepare for required code changes.

---

Step 2: Upgrade React and ReactDOM

Update React packages to the latest version:

npm install react@latest react-dom@latest

Or using Yarn:

yarn add react@latest react-dom@latest

This updates React core without touching your application code.

---

Step 3: Update Type Definitions (If Using TypeScript)

If your project uses TypeScript, also update types:

npm install -D @types/react@latest @types/react-dom@latest

This prevents type mismatch errors.

---

Step 4: Update the Root API (React 18+)

If you upgraded to React 18, you must update the root rendering logic.

❌ Old (React 17 and below)

import ReactDOM from "react-dom";
import App from "./App";

ReactDOM.render(<App />, document.getElementById("root"));

✅ New (React 18+)

import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")).render(
  <App />
);

This enables modern React features and better performance.

---

Step 5: Enable Strict Mode (Recommended)

Wrap your app with StrictMode to catch issues early:

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Note: Strict Mode may cause some effects to run twice in development. This is expected behavior.

---

Step 6: Update Third-Party Dependencies

After upgrading React, update related libraries:

npm outdated
npm update

Pay special attention to:

• UI libraries (MUI, Ant Design, Chakra)
• State management (Redux, Zustand)
• Routing (React Router)

---

Step 7: Run and Test the Application

Start the development server:

npm run dev

Or:

npm start

Test:

• Navigation
• Forms
• API calls
• State updates
• Console warnings

---

Step 8: Fix Common Upgrade Issues

1. ReactDOM.render is not a function

✔ Use createRoot from react-dom/client

---

2. useEffect running twice

✔ Expected in StrictMode (development only)

---

3. Library compatibility errors

✔ Upgrade or replace outdated packages

---

Step 9: Clean Install (Optional but Recommended)

If issues persist:

rm -rf node_modules package-lock.json
npm install

This ensures a clean dependency tree.

---

Final Project Structure (After Upgrade)

my-react-app/
├── package.json
├── node_modules/
└── src/
    ├── App.jsx
    ├── main.jsx
    └── index.css

---

Best Practices for React Upgrades

• Upgrade one major version at a time
• Test thoroughly before production release
• Keep dependencies updated regularly
• Use Strict Mode during development

---

Conclusion

Upgrading React in an existing project doesn’t have to be scary. By following a structured, step-by-step approach, you can safely upgrade React, unlock new features, and keep your project future-ready.

Modern React versions work best with modern tooling like Vite, and staying updated ensures long-term maintainability.

---