React Compiler in Production: Automatic Memoization, Build-Time Optimization, and Migration Strategies for Existing Codebases

Manual memoization in React has always been a bet against the future. You add useMemo when a computation is slow, useCallback when a function identity needs to be stable, React.memo when a child re-renders too often. Six months later, a colleague removes the useCallback because it looks like dead code, and now a deeply nested component re-renders on every keystroke. Nobody catches it because there is no test for render count.

The React Compiler (previously called React Forget) solves a different problem than most performance tooling does. It does not make React faster. It makes the correct optimization the default, so engineers do not have to reason about object identity and referential equality on every component boundary.

This article covers how the compiler works, how to integrate it, what breaks, and when the adoption cost is worth it.

The problem with manual memoization

React’s rendering model is simple: when state changes, the component and all its descendants re-render by default. useMemo, useCallback, and React.memo are escape hatches that opt specific values and components out of that default.

The problem is not that the escape hatches are wrong. The problem is that applying them correctly requires understanding the full render tree, tracking every value’s identity across renders, and maintaining that understanding as the codebase evolves.

Consider a pattern that shows up in most production codebases:

// Before: manually memoized
function ProductList({ categoryId, filters }: Props) {
  const [items, setItems] = useState<Product[]>([]);

  const filteredItems = useMemo(
    () => items.filter(item => matchesFilters(item, filters)),
    [items, filters]  // filters is an object — is this stable?
  );

  const handleSelect = useCallback(
    (id: string) => {
      onSelect(id);
    },
    [onSelect]  // onSelect needs useCallback upstream too
  );

  return <ItemGrid items={filteredItems} onSelect={handleSelect} />;
}

The filters dependency here is an object. If the parent creates it inline (<ProductList filters={{ minPrice: 0 }} />), the useMemo is useless: every render gets a new object reference, so the memo never hits. The developer needs to trace the identity of filters up through the call tree to fix this correctly. Manual memoization does not compose.

How the compiler works

The React Compiler is a build-time Babel transform. It analyzes component and hook source code using static analysis, determines which values can be cached safely between renders, and inserts the equivalent of useMemo/useCallback automatically.

The output is not magic. You can inspect it. A component like:

function Greeting({ name }: { name: string }) {
  const message = `Hello, ${name}`;
  return <div>{message}</div>;
}

Compiles to something structurally similar to:

function Greeting({ name }: { name: string }) {
  const $ = _c(2);
  let message;
  if ($[0] !== name) {
    message = `Hello, ${name}`;
    $[0] = name;
    $[1] = <div>{message}</div>;
  }
  return $[1];
}

The _c call allocates a cache array. The compiler inserts slot-based invalidation: each slot tracks a dependency value, and the cached result is only recomputed when the tracked value changes. This is semantically equivalent to useMemo, but the compiler chooses the cache granularity automatically.

The key insight is that the compiler performs this analysis at the expression level, not the component level. It can cache individual JSX subtrees, individual computed values, and individual callback instances without you specifying the dependency arrays.

Rules of React enforcement

The compiler’s analysis is only sound if components follow the Rules of React:

• Components and hooks must be pure functions with respect to React’s rendering model. No mutating props or state during render.
• Hooks must be called at the top level, unconditionally.
• Refs and external mutable values must not be read or written during render.

These rules already existed before the compiler. The compiler makes them hard requirements rather than guidelines. Components that violate them will either fail to compile or produce incorrect behavior when compiled. The compiler uses a heuristic: it skips components it cannot prove are safe and emits a warning.

Build integration

Babel plugin (framework-agnostic)

Install the compiler package:

npm install --save-dev babel-plugin-react-compiler

Add to your Babel config:

// babel.config.js
module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      compilationMode: 'annotation', // or 'infer' or 'all'
    }],
  ],
};

The compilationMode controls adoption scope. annotation requires explicit opt-in with 'use memo'. infer compiles components the compiler deems safe. all attempts to compile everything and skips on failure.

Vite

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import ReactCompilerConfig from './react-compiler.config';

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

Next.js

Next.js 15 ships with built-in support. Enable it in your config:

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

const nextConfig: NextConfig = {
  experimental: {
    reactCompiler: true,
  },
};

export default nextConfig;

For incremental adoption in Next.js, pass a config object:

const nextConfig: NextConfig = {
  experimental: {
    reactCompiler: {
      compilationMode: 'annotation',
    },
  },
};

Before and after: what actually changes

Here is a more realistic example showing the compiler’s impact on a form component with derived state:

// Source: you write this
function SearchForm({ onSearch, initialQuery }: SearchFormProps) {
  const [query, setQuery] = useState(initialQuery);
  const [debouncedQuery, setDebouncedQuery] = useState(initialQuery);

  const isSubmittable = query.trim().length > 2;

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setQuery(e.target.value);
  };

  const handleSubmit = () => {
    onSearch(query);
  };

  return (
    <form>
      <Input value={query} onChange={handleChange} />
      <Button disabled={!isSubmittable} onClick={handleSubmit}>
        Search
      </Button>
    </form>
  );
}

Without the compiler, handleChange and handleSubmit are new function references every render. Button re-renders even when isSubmittable has not changed, unless you wrap it in React.memo and also wrap handleSubmit in useCallback with [onSearch, query] as dependencies.

With the compiler, these function identities are stabilized automatically. The compiler can also cache the <form> subtree between renders where query, isSubmittable, and the callbacks have not changed.

You do not write any of that. You write the obvious version and the compiler produces the optimized version.

Migration concerns

Components that break the Rules of React

The most common issue in production codebases is mutating state during render or reading from refs at render time:

// This pattern breaks compilation
function BadComponent({ items }: Props) {
  const countRef = useRef(0);
  countRef.current++; // mutation during render — compiler skips this component

  return <div>{countRef.current}</div>;
}

The compiler will either skip this component (in infer mode) or fail noisily (in all mode). Run the compiler’s linting pass first to surface violations:

npx react-compiler-healthcheck

This scans your codebase and produces a report of components that cannot be compiled safely.

Escape hatches

For components where automatic memoization would be incorrect or where you want to explicitly opt out:

function LiveTimer() {
  'use no memo'; // opts this component out of compilation entirely

  const [time, setTime] = useState(new Date());

  useEffect(() => {
    const id = setInterval(() => setTime(new Date()), 1000);
    return () => clearInterval(id);
  }, []);

  return <div>{time.toLocaleTimeString()}</div>;
}

'use no memo' is a directive the compiler respects. Use it when a component intentionally re-renders on every cycle, when it wraps a mutable third-party library, or when compiled output introduces bugs you cannot immediately diagnose.

The inverse directive 'use memo' (annotation mode) opts a specific component in. This is the recommended starting point for large existing codebases: annotate a subset of stable, pure components, verify behavior, expand gradually.

Effects that depend on reference equality

The compiler changes function identity semantics. If you have an effect that uses a callback as a dependency, the behavior can change:

// This effect's behavior depends on whether onDataReceived is stable
useEffect(() => {
  const subscription = dataSource.subscribe(onDataReceived);
  return () => subscription.unsubscribe();
}, [onDataReceived]);

Before the compiler, if onDataReceived was recreated every render (no useCallback), this effect would re-subscribe on every render. That might be a latent bug in your codebase that nobody noticed because the effect ran infrequently. After the compiler stabilizes onDataReceived, the effect runs once. The behavior changes and is now likely correct, but the change can surface as an apparent regression if you were relying on the broken behavior.

This is the category of migration issue that is hardest to catch with tests. Effects that subscribe, connect, or register handlers are particularly vulnerable. Audit these when enabling the compiler.

Third-party libraries with mutable patterns

Some libraries pass mutable objects through React props or expect component callbacks to run on every render. Chart libraries that mutate configuration objects, drag-and-drop libraries that use mutable ref internals, and imperative animation libraries built before hooks are common offenders.

If a library’s README says to pass a config object created inline (e.g., options={{ animations: true }}), the library is probably not designed with React’s rendering model in mind. The compiler will cache that options object, and the library may observe stale configuration.

The fix is usually wrapping the third-party component in a boundary component with 'use no memo', or keeping the library interaction isolated in a custom hook that you annotate carefully.

Measuring performance impact

The React DevTools Profiler remains the correct tool. Enable it in development and record a typical interaction sequence before and after enabling the compiler.

Look at two metrics:

Render count per component. In the Profiler flame chart, components that re-rendered unnecessarily will appear with a render reason of “parent re-rendered.” The compiler should eliminate most of these for components where all props are stable.

Render duration. Memoization has a cost. The cache array allocation and slot comparison add overhead per render. For components that re-render infrequently or are very cheap to render, the compiler’s overhead may exceed its benefit. This is rare in practice but real for trivial leaf components.

You can also use the React Compiler’s own output to understand what was cached. With source maps enabled, the compiled output is inspectable in the browser DevTools. Look for _c() calls and the slot invalidation logic to understand what the compiler decided to cache.

A simple before/after benchmark in a large dashboard application at one production team showed:

• Re-render count per interaction dropped by 40-60% for deeply nested data grids
• Total render time dropped by 25-30% for the same interactions
• No measurable increase in initial render time (the cache initialization overhead is negligible)

These numbers vary by application structure. Data-dense UIs with stable reference problems benefit most. Simple UIs with few components and shallow trees benefit least.

Production gotchas

Debugging compiled output. The compiled output is difficult to read without source maps. Ensure your bundler emits source maps in development. When you see unexpected behavior, disable the compiler for the affected component with 'use no memo' and confirm the behavior changes. This isolates whether the compiler is the cause.

Build time increase. The compiler adds a significant Babel transform step. In a large codebase (hundreds of components), expect a 10-30% increase in cold build time. Incremental builds (hot module replacement) are less affected because Babel operates per-file. If build time is critical, use compilationMode: 'annotation' to limit scope.

React version requirement. The compiler targets React 19+. It uses an internal runtime hook (useMemoCache) that does not exist in earlier versions. If your codebase is on React 18, upgrading is a prerequisite.

Testing. Most unit tests for React components test rendered output and user interactions, which are unaffected by memoization. Tests that assert on render counts or that depend on function reference identity (shallow rendering, enzyme) may need updating. Tests using React Testing Library generally pass without changes.

Decision framework

Factor	Lean toward adopting	Lean toward waiting
React version	19+	18 or below
Codebase purity	Few or no Rules of React violations	Many violations, large audit required
Performance bottleneck	Re-renders from prop identity churn	Slow computation, API latency
Team size	Large team where manual discipline erodes	Small team with tight review discipline
Third-party libraries	Modern, hooks-based libraries	Imperative, mutable-pattern libraries
Adoption strategy	Starting new app or greenfield feature	Full migration of large existing app
Build time tolerance	CI pipeline has headroom	Already at build time limits

The compiler is not the right tool for every performance problem. If your bottleneck is a slow API call, an unvirtualized list of 10,000 rows, or a synchronous computation inside a render, the compiler will not help. It specifically solves the problem of unnecessary re-renders caused by unstable object and function references.

For new applications built on React 19, the default should be to enable the compiler from the start. The Rules of React are good design constraints regardless of compilation. For existing codebases, the annotation mode migration path is lower risk: start with a set of well-behaved utility components, verify, expand.

The deeper value is not the immediate performance gain. It is that future developers writing components do not need to reason about memoization at all. The cognitive load of React performance tuning has been one of the main complaints about the library for years. The compiler does not eliminate that load for debugging, but it eliminates it for authoring. That compounds over time.

Remove the useMemo and useCallback calls from components the compiler handles. Leaving them in place does not break anything, but it creates confusion about which memoization is deliberate and which is redundant.