1 The Problem: Why Manual Memoization Was a Mess

To understand why React Compiler matters, you need to feel the pain it solved. Before it existed, React developers were responsible for manually deciding where memoization was needed — and getting it wrong in either direction caused real problems.

The Re-Render Problem

React's default behavior is to re-render a component and all of its children whenever the component's state or props change. This is fine for simple apps, but in larger applications, a single state change could trigger dozens of unnecessary re-renders — slowing down the UI noticeably.

// Without memoization — EVERY render of Parent re-renders Child,
// even if 'items' hasn't changed at all
function Parent() {
  const [count, setCount] = useState(0);

  // This function is recreated on EVERY render — new reference each time
  const handleSelect = (id: number) => {
    console.log("Selected:", id);
  };

  return (
    <div>
      <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
      {/* Child re-renders every time count changes, even though items didn't change */}
      <ExpensiveList items={items} onSelect={handleSelect} />
    </div>
  );
}

The Manual Fix — and Why It Was Painful

The solution before React Compiler was to wrap things in memoization hooks. But this introduced its own problems: it was verbose, easy to get wrong, and added visual noise that made components harder to read.

// The manual memoization approach — correct, but messy
import { useState, useMemo, useCallback, memo } from 'react';

// Step 1: Wrap the child component in React.memo
const ExpensiveList = memo(function ExpensiveList({ items, onSelect }) {
  return (
    <ul>
      {items.map(item => (
        <ListItem key={item.id} item={item} onSelect={onSelect} />
      ))}
    </ul>
  );
});

function Parent({ rawItems }: { rawItems: RawItem[] }) {
  const [count, setCount] = useState(0);

  // Step 2: Wrap the function in useCallback so its reference stays stable
  const handleSelect = useCallback((id: number) => {
    console.log("Selected:", id);
  }, []); // dependency array — easy to get wrong

  // Step 3: Wrap expensive computation in useMemo
  const processedItems = useMemo(() => {
    return rawItems.map(item => ({ ...item, label: item.name.toUpperCase() }));
  }, [rawItems]); // dependency array — must be correct or you get stale data

  return (
    <div>
      <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
      <ExpensiveList items={processedItems} onSelect={handleSelect} />
    </div>
  );
}

2 What is React Compiler? How It Works

React Compiler (previously known internally at Meta as React Forget) is a build-time tool — not a runtime library. It runs during your build process (via Babel or Webpack), analyzes your React component code, and automatically inserts memoization logic in exactly the right places.

The Core Idea

Instead of you deciding where to add useMemo and useCallback, the compiler reads your code and understands — at a deep level — which values, functions, and JSX subtrees are safe to cache and when they need to be invalidated. It is far more precise than what most developers write by hand.

// What YOU write — clean, plain React code with no optimization hooks
function ProductList({ products, onSelect }) {
  const sortedProducts = products
    .slice()
    .sort((a, b) => a.name.localeCompare(b.name));

  const handleSelect = (id) => {
    onSelect(id);
  };

  return (
    <ul>
      {sortedProducts.map(product => (
        <ProductItem
          key={product.id}
          product={product}
          onSelect={handleSelect}
        />
      ))}
    </ul>
  );
}

// What the COMPILER produces at build time (simplified):
// It automatically creates cache slots for sortedProducts, handleSelect,
// and the JSX subtrees — you never see or write this code yourself.
// It is more granular than React.memo and more precise than typical useMemo calls.

What Exactly Does It Analyze?

The compiler performs static analysis of your component code at build time. It identifies:

• Which values are reactive (change based on props or state)
• Which values are stable (never change or only change when inputs change)
• Which JSX subtrees can be reused without re-rendering
• Which functions can safely have stable references

3 Setting Up React Compiler in Your Project 2026

React Compiler is now straightforward to add to any React project. The setup depends on which framework or build tool you are using.

Option 1: Next.js 16 (Recommended — One Line Setup)

If you are using Next.js 16 or later, React Compiler has stable built-in support. Just add one line to your config:

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  reactCompiler: true, // That's it — one line to enable the compiler
};

export default nextConfig;

Option 2: Vite + React

For Vite-based projects, install the Babel plugin and configure it:

// Step 1: Install the plugin
npm install --save-dev babel-plugin-react-compiler

// Step 2: vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: [
          ['babel-plugin-react-compiler', {}] // Add compiler plugin
        ]
      }
    })
  ]
});

Option 3: Create React App / Webpack

// Step 1: Install
npm install --save-dev babel-plugin-react-compiler

// Step 2: babel.config.js
module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      // Optional: set to 'annotation' during migration to opt-in per file
      compilationMode: 'infer' // Default: automatically compiles all components
    }]
  ]
};

Install the ESLint Plugin (Highly Recommended)

The ESLint plugin for React Compiler surfaces diagnostics directly in your editor — warning you about patterns the compiler cannot optimize safely.

// Install
npm install --save-dev eslint-plugin-react-compiler

// .eslintrc.js
module.exports = {
  plugins: ['react-compiler'],
  rules: {
    'react-compiler/react-compiler': 'error'
  }
};

4 Before vs After: Real Code Comparisons Important

The best way to understand the React Compiler's impact is to see real before-and-after examples side by side. These are patterns that appear in almost every real React application.

Example 1: Sorted Product List

// ❌ BEFORE React Compiler — manual memoization required
import { useMemo, useCallback, memo } from 'react';

const ProductItem = memo(function ProductItem({ product, onSelect }) {
  return <li onClick={() => onSelect(product.id)}>{product.name}</li>;
});

function ProductList({ products, onSelect }) {
  const sortedProducts = useMemo(() => {
    return products.slice().sort((a, b) => a.name.localeCompare(b.name));
  }, [products]);

  const handleSelect = useCallback((id) => {
    onSelect(id);
  }, [onSelect]);

  return (
    <ul>
      {sortedProducts.map(product => (
        <ProductItem key={product.id} product={product} onSelect={handleSelect} />
      ))}
    </ul>
  );
}

// ✅ AFTER React Compiler — write plain code, compiler handles optimization
function ProductItem({ product, onSelect }) {
  return <li onClick={() => onSelect(product.id)}>{product.name}</li>;
}

function ProductList({ products, onSelect }) {
  const sortedProducts = products
    .slice()
    .sort((a, b) => a.name.localeCompare(b.name));

  const handleSelect = (id) => {
    onSelect(id);
  };

  return (
    <ul>
      {sortedProducts.map(product => (
        <ProductItem key={product.id} product={product} onSelect={handleSelect} />
      ))}
    </ul>
  );
}
// React Compiler automatically memoizes sortedProducts, handleSelect,
// and ProductItem — with MORE precision than the manual version above ✅

Example 2: Dashboard with Multiple Data Sources

// ❌ BEFORE — every optimization hook written by hand
function Dashboard({ userId, theme }) {
  const [filter, setFilter] = useState('all');

  const filteredData = useMemo(() => {
    return rawData.filter(item => filter === 'all' || item.type === filter);
  }, [rawData, filter]);

  const chartConfig = useMemo(() => ({
    color: theme === 'dark' ? '#fff' : '#333',
    fontSize: 14
  }), [theme]);

  const handleFilterChange = useCallback((newFilter) => {
    setFilter(newFilter);
  }, []);

  const handleExport = useCallback(() => {
    exportData(filteredData);
  }, [filteredData]);

  return <DashboardUI data={filteredData} config={chartConfig}
                       onFilter={handleFilterChange} onExport={handleExport} />;
}

// ✅ AFTER — clean code, zero optimization hooks
function Dashboard({ userId, theme }) {
  const [filter, setFilter] = useState('all');

  const filteredData = rawData.filter(
    item => filter === 'all' || item.type === filter
  );

  const chartConfig = {
    color: theme === 'dark' ? '#fff' : '#333',
    fontSize: 14
  };

  const handleFilterChange = (newFilter) => setFilter(newFilter);
  const handleExport = () => exportData(filteredData);

  return <DashboardUI data={filteredData} config={chartConfig}
                       onFilter={handleFilterChange} onExport={handleExport} />;
}
// The compiler memoizes each value precisely — only re-computing when
// its specific dependencies actually change ✅

5 How the Compiler Decides What to Memoize

Understanding the compiler's decision-making helps you write code that it can optimize effectively. The compiler uses static analysis — it reads your code like a very smart linter and maps out all the data dependencies in your component.

Reactive vs Stable Values

The compiler categorizes everything in your component into two buckets:

• Reactive values — props, state, and anything derived from them. These can change between renders.
• Stable values — constants, module-level variables, and values whose inputs haven't changed. These can be safely cached.

function UserCard({ user, isAdmin }) {
  // 'user' and 'isAdmin' are reactive — they come from props
  // The compiler knows these might change between renders

  const displayName = `${user.firstName} ${user.lastName}`;
  // 'displayName' depends on 'user' — reactive, cached per 'user' value

  const adminLabel = isAdmin ? "Administrator" : "Member";
  // 'adminLabel' depends on 'isAdmin' — reactive, cached per 'isAdmin' value

  const API_BASE = "https://api.example.com";
  // This is a constant — stable, never needs caching

  return (
    <div>
      <h2>{displayName}</h2>
      <span>{adminLabel}</span>
    </div>
  );
}
// The compiler creates separate cache slots for displayName and adminLabel.
// If only 'isAdmin' changes, 'displayName' is NOT recomputed. ✅

What the Compiler Does NOT Memoize

The compiler focuses specifically on React components and hooks. There are some important cases it intentionally skips:

• Regular utility functions that are not React components or hooks
• Expensive computations that are shared across multiple components — these should still use external memoization like a global cache or state management library
• Code that mutates props or state — this breaks React's rules and the compiler will skip it
• Calls to external functions with internal mutability that the compiler cannot see through

6 When You Still Need useMemo and useCallback Important

React Compiler handles the vast majority of memoization needs automatically. But there are specific situations — mostly involving third-party libraries — where you still need to write manual memoization. Knowing these cases prevents hard-to-debug bugs after migration.

Case 1: Libraries With Interior Mutability

Some libraries return functions or objects where the reference stays the same but the internal value changes. The compiler cannot see through these — it assumes stable references are stable — so you need manual memoization.

import { useForm } from 'react-hook-form';

function SearchForm({ onSearch }) {
  const { watch } = useForm();

  // ⚠️ 'watch' has interior mutability — the function reference stays stable
  // but its return value changes. The compiler can't detect this.
  // You need useMemo here to correctly track when the value changes:
  const searchQuery = useMemo(() => watch('query'), [watch]);

  useEffect(() => {
    onSearch(searchQuery);
  }, [searchQuery, onSearch]);

  return <input {...register('query')} />;
}

Case 2: Drag-and-Drop and Libraries Using Reference Equality

Some libraries like react-dnd rely on reference equality to detect changes. If the compiler gives your handler a new reference (which it might in certain analysis scenarios), the library re-registers the whole drag setup every render.

import { useDrag } from 'react-dnd';

function DraggableCard({ id, onDrop }) {
  // Keep useCallback here — react-dnd depends on reference stability
  const handleDrop = useCallback((item) => {
    onDrop(id, item);
  }, [id, onDrop]);

  const [, drag] = useDrag({
    type: 'CARD',
    end: handleDrop
  });

  return <div ref={drag}>Drag me</div>;
}

Case 3: useEffect Dependencies That Must Not Re-Fire

When a memoized value is used as a useEffect dependency, you may need to ensure the effect doesn't fire repeatedly even when the computed value hasn't meaningfully changed.

function DataFetcher({ filters }) {
  // This object is recreated every render — useEffect would fire on every render
  // The compiler memoizes it, but you can be explicit when using it as an effect dep
  const queryParams = useMemo(() => ({
    category: filters.category,
    minPrice: filters.minPrice,
    maxPrice: filters.maxPrice
  }), [filters.category, filters.minPrice, filters.maxPrice]);

  useEffect(() => {
    fetchData(queryParams);
  }, [queryParams]); // Only re-fetches when query params actually change ✅
}

7 Escape Hatches: "use no memo" and "use memo" 2026

React Compiler provides two special directives — string literals you place at the top of a function — that give you control when the compiler's automatic behavior isn't what you want.

"use no memo" — Opt a Component OUT of Compilation

If the compiler is causing issues with a specific component (rare, but it can happen with complex state mutations or unusual patterns), you can tell it to skip that component entirely.

function ProblematicComponent({ data }) {
  "use no memo"; // Tell the compiler to skip this component entirely

  // The rest of your component works exactly as before — no compiler optimization
  // Use this ONLY when you have confirmed the compiler causes a real bug here
  // It is temporary — file an issue with the React team and remove it once fixed

  const result = complexMutationLogic(data);
  return <div>{result}</div>;
}

"use memo" — Force a Function to Be Compiled

By default, the compiler in infer mode (the default) automatically decides which functions to compile based on naming conventions. If you have a utility function that follows React patterns but isn't being compiled, you can opt it in explicitly.

function useCustomHook(value: string) {
  "use memo"; // Explicitly opt this function into React Compiler optimization

  const processedValue = value.trim().toLowerCase();
  const isValid = processedValue.length > 0;

  return { processedValue, isValid };
}

// Note: Hooks and components named with the correct conventions (useXxx, XxxComponent)
// are automatically inferred for compilation. "use memo" is only needed for edge cases.

8 Migrating an Existing Codebase

If you have an existing React project full of useMemo, useCallback, and React.memo calls, migration does not have to be risky or all-at-once. Here is the recommended phased approach used by teams that have successfully migrated large codebases.

Phase 1: Audit With ESLint First (Before Enabling the Compiler)

// Install eslint-plugin-react-compiler
npm install --save-dev eslint-plugin-react-compiler

// Run it on your entire codebase — it shows you which components have issues
// Fix all warnings before enabling the compiler for a smooth migration
npx eslint --ext .tsx,.ts src/ --rule 'react-compiler/react-compiler: error'

Phase 2: Enable in Annotation Mode (Gradual Opt-In)

Start with compilationMode: 'annotation' — this tells the compiler to only optimize files that you explicitly opt into by adding "use memo" at the top. This lets you test the compiler on a few safe components before rolling it out everywhere.

// babel.config.js — opt-in mode for gradual migration
module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      compilationMode: 'annotation' // Only compiles files with "use memo"
    }]
  ]
};

// In each component file you want to test:
function SafeComponent({ data }) {
  "use memo"; // This file is now compiled — test it works correctly
  // ...
}

Phase 3: Switch to Full Compilation (infer mode)

Once you are confident, switch to the default infer mode which compiles all components automatically.

// babel.config.js — full compilation
module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      compilationMode: 'infer' // Default — compiles everything automatically
    }]
  ]
};

Phase 4: Remove Manual Memoization (Cleanup)

After confirming the compiler works correctly across your app, remove the manual optimization hooks. There is codemod tooling available that can automate this cleanup:

// Automated removal of useMemo/useCallback/React.memo wrappers
// that the compiler now handles — use this only after thorough testing
npx codemod react-compiler/remove-manual-memoization src/

// Then manually review the diff and run your test suite
// Keep manual hooks ONLY in the cases described in Section 6

9 Verifying the Compiler is Working (DevTools + ESLint)

After enabling React Compiler, you want to confirm it is actually optimizing your components. React DevTools makes this easy with a visual indicator.

The ✨ Badge in React DevTools

Install React DevTools (browser extension) and open the Components tab. Every component that has been successfully optimized by the React Compiler shows a ✨ sparkle badge next to its name in the component tree.

// If you see this in React DevTools component tree:
// ✨ ProductList       <-- Compiled and optimized by React Compiler ✅
//    ProductItem       <-- Also compiled ✅
//    FilterBar         <-- Also compiled ✅

// If a component is missing the ✨ badge, it means the compiler
// could not safely optimize it — check the ESLint plugin for warnings

Measuring Re-Render Reduction

Use the React DevTools Profiler tab to measure the impact before and after enabling the compiler. Record a session of interactions, and compare how many components re-render on each action.

// In React DevTools Profiler:
// 1. Click "Record" before enabling compiler → perform some interactions → Stop
// 2. Note how many components re-rendered on each action

// After enabling compiler:
// 3. Record again → same interactions → Stop
// 4. Compare: you should see significantly fewer re-renders for the same actions

// What to look for:
// Before: count changes → 15 components re-render
// After:  count changes → 3 components re-render (only the ones that depend on count)

10 Common Mistakes and What to Avoid

Even with React Compiler handling the heavy lifting, there are patterns that break its analysis or lead to unexpected behavior. Avoid these in your code.

Mistake 1 — Mutating Props or State

This is the biggest one. Directly mutating props or state breaks React's rules and causes the compiler to bail out of optimizing that component. It can also cause silent, hard-to-debug bugs.

// ❌ WRONG — Mutating a prop directly. The compiler skips this component.
function BadComponent({ items }) {
  items.push({ id: 99, name: "Extra" }); // NEVER mutate props!
  return <ul>{items.map(i => <li key={i.id}>{i.name}</li>)}</ul>;
}

// ✅ CORRECT — Create a new array instead of mutating
function GoodComponent({ items }) {
  const extendedItems = [...items, { id: 99, name: "Extra" }]; // New array
  return <ul>{extendedItems.map(i => <li key={i.id}>{i.name}</li>)}</ul>;
}

Mistake 2 — Removing All useMemo and useCallback at Once Without Testing

// ❌ DANGEROUS — Removing all hooks at once without verifying compiler is active
// If the compiler isn't set up correctly, you'll have a performance regression
// Always verify the ✨ badge in DevTools BEFORE removing manual hooks

// ✅ CORRECT — Gradual migration with verification at each step
// 1. Enable compiler → verify ✨ badges → then remove hooks one component at a time

Mistake 3 — Calling Hooks Conditionally

// ❌ WRONG — Conditional hooks break React's rules AND break the compiler
function BadForm({ isAdmin }) {
  if (isAdmin) {
    const data = useAdminData(); // NEVER call hooks conditionally!
  }
  return <form>...</form>;
}

// ✅ CORRECT — Always call hooks unconditionally
function GoodForm({ isAdmin }) {
  const data = useAdminData(); // Always called
  const adminData = isAdmin ? data : null; // Conditional logic after the hook
  return <form>...</form>;
}

Mistake 4 — Assuming the Compiler Handles All Performance Issues

// ❌ WRONG assumption — the compiler only prevents unnecessary RE-renders.
// It does NOT fix slow initial renders or heavy synchronous computations.

function SlowComponent({ millionItems }) {
  // This runs on EVERY render and is still slow — the compiler caches the result,
  // but the first render still takes the full time
  const result = millionItems.reduce((acc, item) => acc + item.value, 0);
  return <span>Total: {result}</span>;
}

// ✅ If the calculation is truly expensive and the data is shared,
// use a server-side calculation, Web Worker, or global cache instead

11 Best Practices Checklist

Use this checklist when setting up React Compiler or reviewing your components after migration.

Setup

• Install eslint-plugin-react-compiler and fix all warnings before enabling the compiler.
• Use compilationMode: 'annotation' for gradual migration in large codebases.
• Switch to compilationMode: 'infer' (default) for full automatic compilation.
• Verify the ✨ badge appears in React DevTools for your components after setup.
• Measure re-render counts in the Profiler before and after to confirm improvement.

Writing Components With the Compiler

• Write plain, clean React code — no useMemo, useCallback, or React.memo needed for most components.
• Never mutate props, state, or context — always create new objects or arrays.
• Always call hooks unconditionally and at the top level of your component.
• Keep components pure — same inputs should always produce the same output.
• Do not read refs during render — refs are for side effects only.

When to Still Use Manual Hooks

• Third-party libraries with interior mutability (e.g., react-hook-form's watch).
• Libraries that depend on reference equality (e.g., react-dnd).
• Effect dependencies where you need explicit control over when effects re-fire.
• Use "use no memo" as a temporary escape hatch — never as a long-term solution.

Migration

• Do not remove manual hooks immediately — the compiler works safely alongside them.
• Use codemod tooling for automated hook removal after thorough testing.
• Test every component that relied on manual memoization before and after migration.
• Run your full test suite after each migration phase.