React Reference ยท Rules of React
React Compiler
Reference for React Compiler: what it memoizes, the code rules it relies on, how to set it up, opt out with directives, and how it compares to useMemo.
React Compiler is a build-time tool that rewrites your components and hooks so that React can skip work when the inputs have not changed. It does the job you would otherwise do by hand with memo, useMemo and useCallback, but for the whole component at once, including values and JSX you would never think to wrap.
The compiler can only do this safely because React code follows rules: components are pure, props and state are never mutated, and hooks are called in a stable order. It does not fix code that breaks the rules. When it cannot prove a component is safe, it leaves that component alone and compiles the rest.
// babel config: the compiler plugin must come first module.exports = { plugins: [['babel-plugin-react-compiler', {}]], };
Try it
You cannot run the compiler in the browser, so this example shows the effect it aims for, written by hand. The component below does an "expensive" calculation. Without caching it runs on every render, even when only an unrelated counter changed. With useMemo it runs only when its input changes. The compiler adds this kind of caching for you.
Open the console and press the button. The "up to 1000" line appears on every click, and "up to 2000" appears only once.
The compiler's main requirement is that rendering must be pure. This second example breaks that rule by changing a variable outside the component during render. In development, StrictMode renders twice and exposes the problem, because the count jumps by two.
The first screen already shows a counter of 2 although the component rendered "once". Code like this makes memoization unsafe: skipping a render would also skip the write. The compiler (and the lint rules) treat it as a violation.
Syntax
Setup depends on your build tool, but the shape is always "add the Babel plugin".
// Vite with @vitejs/plugin-react react({ babel: { plugins: [['babel-plugin-react-compiler', {}]] } })
| Option / directive | Description |
|---|---|
compilationMode: 'infer' |
Default. Compiles functions it recognizes as components or hooks. |
compilationMode: 'annotation' |
Compiles only functions that contain the 'use memo' directive. Useful for gradual adoption. |
compilationMode: 'all' |
Tries to compile every top-level function. |
'use no memo' |
A directive at the top of a function body that excludes it from compilation, for example while you debug a problem. |
target |
'19' is the default. For React 17 or 18 set '17' or '18' and install react-compiler-runtime. |
panicThreshold |
Controls whether the build fails on code the compiler cannot handle. The default is to skip such code silently. |
function Chart({ data }) { 'use no memo'; // this component is not compiled }
Usage notes
- Install the lint rules first. The compiler's checks are also available in eslint-plugin-react-hooks, so you can see which components would be skipped before you turn the compiler on.
- Skipped components are silent. If a component breaks a rule (mutating props, reading a ref during render, a conditional hook), the compiler does not compile it and does not complain at runtime. React DevTools shows a "Memo" badge on compiled components.
- Manual
useMemoanduseCallbackstill work. The compiler respects them, and existing code does not need to be removed. Use them when you need a stable identity as an effect dependency. - It does not change behavior when your code follows the rules. If turning it on changes what your app does, a rule was already broken; try
'use no memo'on the suspect component and fix the cause. - It memoizes rendering, not effects. It cannot decide that an effect is unnecessary; see You might not need an effect.
- No runtime for React 19. The compiled code uses a cache helper that React 19 provides, which is why older versions need the extra runtime package.
- It does not replace measurements. Slow code that does a lot of work per render still does that work the first time. Profile before you rewrite.