React Compiler v1.0 Complete Guide — Automatic Memoization Principles and Practical Application

Have you ever manually written useMemo, useCallback, and React.memo to prevent unnecessary re-renders, and checked every time whether the dependency array was correct? If you have used React for a while, you will understand how cumbersome and error-prone this manual optimization process is. On October 7, 2025, the React team officially released React Compiler v1.0, which automatically resolves this issue at build time.

The effectiveness of the compiler has already been confirmed in actual services. Up to 12% improvement in load performance has been reported in the Meta Quest Store (InfoQ Report), a 20–30% reduction in render times in Sanity Studio (Sanity Official Documentation), and a 10% improvement in LCP in Wakelet (DebugBear Analysis). However, these figures are results measured in specific codebases of each team, and actual effects vary significantly depending on the project structure.

With Next.js 15 and Expo SDK 54 enabling the React Compiler by default, understanding this tool is a change that frontend developers with experience in React performance optimization should grasp quickly. This article covers everything from how the React Compiler works to practical applications and common pitfalls in one go.

Key Concepts

What is React Compiler

React Compiler is a build-time optimization tool that operates as a Babel plugin. It intervenes at the point where the bundler processes code to analyze React components and hooks and generate optimized code.

Looking at the internal workflow, the compiler converts the AST (Abstract Syntax Tree) generated by Babel parsing the source code into its own format, HIR (High-level Intermediate Representation). Subsequently, it sequentially passes through several analysis stages to apply optimizations.

HIR (High-level Intermediate Representation): An intermediate representation format used instead of directly analyzing source code. It has a higher level of abstraction than AST, making it advantageous for conversion into a control flow graph, which allows the compiler to precisely track variable scope and data flow.

Compiler Pass: Refers to the stage where the compiler analyzes the code sequentially multiple times. In each pass, specific tasks are performed, such as data flow analysis, mutability checks, and optimization insertion.

Based on this analysis, granular conditional memoization is automatically inserted only for code that the compiler determines to be "safe."

How Automatic Memoization Works

Compiler memoization is not limited to the component level. It can automatically apply caching to granular units such as JSX expressions, inline object literals, and callback functions, enabling optimizations that are difficult to achieve with manual memoization.

Below is a conceptual comparison showing what the compiler does on behalf of others.

javascript

// 개발자가 작성하는 코드 (Before)
function TodoList({ todos, onToggle }) {
  return (
    <ul>
      {todos.map(todo => (
        <li key={todo.id} onClick={() => onToggle(todo.id)}>
          {todo.text}
        </li>
      ))}
    </ul>
  );
}

javascript

// 컴파일러가 생성하는 최적화 결과 (개념적 표현 — 실제 출력은 내부 캐싱 API를 사용하는 저수준 코드입니다, After)
const TodoList = React.memo(function TodoList({ todos, onToggle }) {
  const handleToggle = useCallback((id) => onToggle(id), [onToggle]);
  const memoizedList = useMemo(
    () =>
      todos.map(todo => (
        <li key={todo.id} onClick={() => handleToggle(todo.id)}>
          {todo.text}
        </li>
      )),
    [todos, handleToggle]
  );
  return <ul>{memoizedList}</ul>;
});

Developers can write code as usual, and the compiler automatically inserts React.memo, useMemo, and useCallback at build time. Function references that were newly created for every render, such as the onToggle callback, are also automatically stabilized.

Prerequisites for Application

The React Compiler applies optimization only to code that complies with the Rules of React. Code that violates the rules is silently excluded from optimization (Silent Failures) and skipped without any separate errors. Typical examples of rule violations are as follows:

Violation Pattern	Example
Change props directly	`props.list.push(item)`
Side effects during rendering	Direct call to `fetch()` within the render function
Complex try/catch structures	Patterns where the compiler gives up on flow analysis
Hook rule violation	Hook call inside conditional statement

Practical Application

Example 1: Apply to the entire app in a single line in Next.js

If you are using Next.js, you can enable the React Compiler for the entire app with a single line in the configuration file.

typescript

// next.config.ts
import type { NextConfig } from 'next';
 
const nextConfig: NextConfig = {
  reactCompiler: true,
};
 
export default nextConfig;

Next.js integrates a compiler based on SWC, so it is applied immediately without separate Babel configuration. If you want to introduce it gradually while minimizing the impact on your existing codebase, you can also configure compilationMode: 'annotation'.

javascript

// next.config.ts — 점진적 도입 (opt-in 모드)
const nextConfig: NextConfig = {
  reactCompiler: {
    compilationMode: 'annotation',
  },
};
 
export default nextConfig;

In opt-in mode, the compiler applies only to components that have the "use memo" directive added to the top of the file.

javascript

// components/ExpensiveComponent.tsx
"use memo";  // 이 파일의 컴포넌트에만 컴파일러 적용
 
export function ExpensiveComponent({ data }) {
  // 무거운 연산이 포함된 컴포넌트
  return <div>{/* ... */}</div>;
}

Example 2: Applying the Babel plugin in a Vite project

For Vite-based projects, you can apply this by adding babel-plugin-react-compiler. Currently, the official React Compiler package is stably provided based on Babel. For projects using @vitejs/plugin-react-swc, since support for the React Compiler plugin for SWC is still in an experimental stage, we recommend switching to @vitejs/plugin-react (Babel-based) for stable application.

pnpm add -D babel-plugin-react-compiler

javascript

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
 
export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: ['babel-plugin-react-compiler'],
      },
    }),
  ],
});

The latest scaffold template for npm create vite@latest already includes a React Compiler option, so if you are new to a project, you can immediately select whether to enable it when choosing the template.

Example 3: Pre-implementation Codebase Diagnosis

Before introducing React Compiler to an existing project, it is a good idea to check the compilation rate using the react-compiler-healthcheck CLI in advance.

npx react-compiler-healthcheck@latest

The actual output displays the full compilation results along with a classification of the reasons why optimization was not possible.

Successfully compiled 1,231 out of 1,411 components.
 
Components skipped (180):
  - Rules of React violations:       89 components
  - Unsupported syntax patterns:     56 components
  - Side effects detected in render: 35 components

This report allows you to identify priorities for "which patterns to modify first to increase the compilation rate." In the case of Sanity Studio, 87% were compilable (Sanity Official Documentation), and this rate tends to be proportional to the actual performance improvement.

Pros and Cons Analysis

Advantages

Item	Content
Code Simplification	No need to manually write `useMemo`, `useCallback`, `React.memo`
Automatic Optimization	Optimization points missed by developers are automatically handled through static analysis
Improved maintainability	Reduced likelihood of bugs caused by dependency array errors (`exhaustive-deps`)
Gradual Adoption	You can apply it to existing codebases in stages via opt-in/opt-out mode
Framework Integration	Official support for major frameworks such as Next.js, Expo, and Vite is complete
Granular Caching	Caching for JSX expressions, inline object literals, and callbacks is also automatically applied

Disadvantages and Precautions

Item	Content	Response Plan
Silent Failures	Code that cannot be optimized is silently skipped, making it difficult to identify which components are optimized	Check with the `Memo ✨` badge in React DevTools or pre-diagnose with ESLint rules
Partial Optimization	It optimizes the rendering method (HOW) but does not control whether or not to render (WHETHER). For example, if the `count` state of a parent component changes, the child may be re-rendered even if the props passed to it do not change, and the compiler does not prevent this re-rendering itself.	It is appropriate to resolve structural unnecessary rendering issues at the state design level.
Code Pattern Constraints	Unsupported patterns exist, such as direct prop modification and complex try/catch blocks	Identify these patterns in advance using `react-compiler-healthcheck` and organize them
Variable Effects	Performance improvement varies significantly from 0% to 60% depending on codebase characteristics	Measure in a real-world environment before implementation to set realistic expectations
React Rules Compliance Mandatory	Existing code that violates the Rules of React is automatically excluded from compilation	`eslint-plugin-react-hooks` v6+ identifies and fixes violating code in advance
Third-party library compatibility	Unexpected behavior may occur when used with state management libraries such as Zustand or Jotai, or animation libraries such as Framer Motion	Utilize the `"use no memo"` directive to exclude the component from the compiler target

eslint-plugin-react-hooks v6+: This is a version with integrated React Compiler lint rules. It includes new rules such as set-state-in-render, set-state-in-effect, and refs, and can be used without installing eslint-plugin-react-compiler separately.

"use no memo" Directive: Add this to the top of your file when you want to explicitly exclude specific components from the compiler. This can be used for components that wrap third-party libraries that conflict with the compiler, or for legacy components with complex side effects.

The Most Common Mistakes in Practice

Interpreting the Memo ✨ badge in DevTools as a guarantee of optimization success — This badge merely indicates that the compiler has processed the component and does not mean that actual performance has improved. It is recommended to perform performance measurements separately using Lighthouse or React Profiler.
Introducing the compiler without cleaning up existing incorrect useMemo/useCallback — If manual memoization code with incorrect dependency arrays remains, it may conflict with the compiler's analysis results. It is recommended to clean up the code with ESLint before introduction.
Applying to the entire app at once — Especially for large legacy codebases, it is safe to start in opt-in mode (compilationMode: 'annotation') and apply gradually by checking on components.

In Conclusion

If you apply React Compiler directly to your codebase, you will notice a surprising amount of boilerplate code disappearing, reminiscent of the days when you manually managed dependency arrays. React Compiler v1.0 creates an environment where developers can focus on business logic by delegating the cognitive burden of memoization management to the compiler. However, since the extent of effectiveness varies depending on the characteristics of the codebase, it is important to set realistic expectations through actual measurements before implementation.

3 Steps to Start Right Now:

Existing Project Diagnosis — You can run npx react-compiler-healthcheck@latest to check the compilability rate of the current codebase. If it is 80% or higher, you can expect immediate implementation benefits.
ESLint Upgrade and Cleanup of Violating Code — It is recommended to first install v6+ using pnpm add -D eslint-plugin-react-hooks@latest and identify and fix code violating Rules of React using the new lint rules.
Gradual application in opt-in mode — If using Next.js, configure compilationMode: 'annotation'; if using Vite, configure the Babel plugin, then use the "use memo" directive to apply it one by one, starting with performance-critical components. It is recommended to verify the effects by comparing the before and after results using React DevTools and React Profiler.

Next Post: Core Features of React 19 Designed with React Compiler — We will explore how the Actions API and use hooks are changing data fetching patterns.

Reference Materials

frontend

React Compiler v1.0 Complete Guide — Automatic Memoization Principles and Practical Application

Key Concepts

What is React Compiler

Based on this analysis, granular conditional memoization is automatically inserted only for code that the compiler determines to be "safe."

How Automatic Memoization Works

Below is a conceptual comparison showing what the compiler does on behalf of others.

javascript

// 개발자가 작성하는 코드 (Before)
function TodoList({ todos, onToggle }) {
  return (
    <ul>
      {todos.map(todo => (
        <li key={todo.id} onClick={() => onToggle(todo.id)}>
          {todo.text}
        </li>
      ))}
    </ul>
  );
}

javascript

// 컴파일러가 생성하는 최적화 결과 (개념적 표현 — 실제 출력은 내부 캐싱 API를 사용하는 저수준 코드입니다, After)
const TodoList = React.memo(function TodoList({ todos, onToggle }) {
  const handleToggle = useCallback((id) => onToggle(id), [onToggle]);
  const memoizedList = useMemo(
    () =>
      todos.map(todo => (
        <li key={todo.id} onClick={() => handleToggle(todo.id)}>
          {todo.text}
        </li>
      )),
    [todos, handleToggle]
  );
  return <ul>{memoizedList}</ul>;
});

Prerequisites for Application

Violation Pattern	Example
Change props directly	`props.list.push(item)`
Side effects during rendering	Direct call to `fetch()` within the render function
Complex try/catch structures	Patterns where the compiler gives up on flow analysis
Hook rule violation	Hook call inside conditional statement

Practical Application

Example 1: Apply to the entire app in a single line in Next.js

If you are using Next.js, you can enable the React Compiler for the entire app with a single line in the configuration file.

typescript

// next.config.ts
import type { NextConfig } from 'next';
 
const nextConfig: NextConfig = {
  reactCompiler: true,
};
 
export default nextConfig;

javascript

// next.config.ts — 점진적 도입 (opt-in 모드)
const nextConfig: NextConfig = {
  reactCompiler: {
    compilationMode: 'annotation',
  },
};
 
export default nextConfig;

In opt-in mode, the compiler applies only to components that have the "use memo" directive added to the top of the file.

javascript

// components/ExpensiveComponent.tsx
"use memo";  // 이 파일의 컴포넌트에만 컴파일러 적용
 
export function ExpensiveComponent({ data }) {
  // 무거운 연산이 포함된 컴포넌트
  return <div>{/* ... */}</div>;
}

Example 2: Applying the Babel plugin in a Vite project

pnpm add -D babel-plugin-react-compiler

javascript

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
 
export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: ['babel-plugin-react-compiler'],
      },
    }),
  ],
});

Example 3: Pre-implementation Codebase Diagnosis

Before introducing React Compiler to an existing project, it is a good idea to check the compilation rate using the react-compiler-healthcheck CLI in advance.

npx react-compiler-healthcheck@latest

The actual output displays the full compilation results along with a classification of the reasons why optimization was not possible.

Successfully compiled 1,231 out of 1,411 components.
 
Components skipped (180):
  - Rules of React violations:       89 components
  - Unsupported syntax patterns:     56 components
  - Side effects detected in render: 35 components

Pros and Cons Analysis

Advantages

Item	Content
Code Simplification	No need to manually write `useMemo`, `useCallback`, `React.memo`
Automatic Optimization	Optimization points missed by developers are automatically handled through static analysis
Improved maintainability	Reduced likelihood of bugs caused by dependency array errors (`exhaustive-deps`)
Gradual Adoption	You can apply it to existing codebases in stages via opt-in/opt-out mode
Framework Integration	Official support for major frameworks such as Next.js, Expo, and Vite is complete
Granular Caching	Caching for JSX expressions, inline object literals, and callbacks is also automatically applied

Disadvantages and Precautions

Item	Content	Response Plan
Silent Failures	Code that cannot be optimized is silently skipped, making it difficult to identify which components are optimized	Check with the `Memo ✨` badge in React DevTools or pre-diagnose with ESLint rules
Partial Optimization	It optimizes the rendering method (HOW) but does not control whether or not to render (WHETHER). For example, if the `count` state of a parent component changes, the child may be re-rendered even if the props passed to it do not change, and the compiler does not prevent this re-rendering itself.	It is appropriate to resolve structural unnecessary rendering issues at the state design level.
Code Pattern Constraints	Unsupported patterns exist, such as direct prop modification and complex try/catch blocks	Identify these patterns in advance using `react-compiler-healthcheck` and organize them
Variable Effects	Performance improvement varies significantly from 0% to 60% depending on codebase characteristics	Measure in a real-world environment before implementation to set realistic expectations
React Rules Compliance Mandatory	Existing code that violates the Rules of React is automatically excluded from compilation	`eslint-plugin-react-hooks` v6+ identifies and fixes violating code in advance
Third-party library compatibility	Unexpected behavior may occur when used with state management libraries such as Zustand or Jotai, or animation libraries such as Framer Motion	Utilize the `"use no memo"` directive to exclude the component from the compiler target

The Most Common Mistakes in Practice

Interpreting the Memo ✨ badge in DevTools as a guarantee of optimization success — This badge merely indicates that the compiler has processed the component and does not mean that actual performance has improved. It is recommended to perform performance measurements separately using Lighthouse or React Profiler.
Introducing the compiler without cleaning up existing incorrect useMemo/useCallback — If manual memoization code with incorrect dependency arrays remains, it may conflict with the compiler's analysis results. It is recommended to clean up the code with ESLint before introduction.
Applying to the entire app at once — Especially for large legacy codebases, it is safe to start in opt-in mode (compilationMode: 'annotation') and apply gradually by checking on components.

In Conclusion

3 Steps to Start Right Now:

Existing Project Diagnosis — You can run npx react-compiler-healthcheck@latest to check the compilability rate of the current codebase. If it is 80% or higher, you can expect immediate implementation benefits.
ESLint Upgrade and Cleanup of Violating Code — It is recommended to first install v6+ using pnpm add -D eslint-plugin-react-hooks@latest and identify and fix code violating Rules of React using the new lint rules.
Gradual application in opt-in mode — If using Next.js, configure compilationMode: 'annotation'; if using Vite, configure the Babel plugin, then use the "use memo" directive to apply it one by one, starting with performance-critical components. It is recommended to verify the effects by comparing the before and after results using React DevTools and React Profiler.

Next Post: Core Features of React 19 Designed with React Compiler — We will explore how the Actions API and use hooks are changing data fetching patterns.