reactCompiler
Turns on automatic memoization so components re-render less without manual useMemo calls.
reactCompiler?: boolean | {
compilationMode?: 'annotation'
}- Added in Next.js v16.0.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$reactCompileroptional | boolean | object= false | `true` enables the React Compiler for the whole project. An object form configures it instead of just switching it on. |
$compilationModeoptional | 'annotation' | Set to `'annotation'` to run in opt-in mode, where only components and hooks carrying the React `"use memo"` directive are compiled. |
$experimental.turbopackRustReactCompileroptional | boolean= false | Runs the native Rust port of the React Compiler inside Turbopack instead of the Babel transform. Requires `reactCompiler` to be enabled; it selects an implementation, it does not turn the compiler on. |
Errors
Enabling `experimental.turbopackRustReactCompiler` while building with webpack throws an error — that option is only supported with Turbopack.
Changelog
- PHP v16.3.0Introduced the experimental `turbopackRustReactCompiler` option for the native Rust React Compiler.
- PHP v16.0.0Built-in React Compiler support became stable following React Compiler 1.0; the option was promoted from `experimental` to top level. It is still not enabled by default.
The React Compiler rewrites your components so React skips re-rendering work automatically, removing most of the reason to hand-write useMemo and useCallback. Next.js layers an SWC pass on top that scans the project first and only feeds files containing JSX or React Hooks to the compiler, so builds do less work than running the Babel plugin directly.
When to reach for it
Turn it on when an interactive Client Component tree re-renders more than it should and the memoization hooks are piling up. It is stable but deliberately off by default, so treat it as a measured change: benchmark your build time before and after.
What trips people up
- You must install
babel-plugin-react-compileryourself. The config flag alone does nothing without it, unless you are on the Rust port. - Because the default path runs through Babel, expect development and build compile times to rise. This is the most common surprise.
experimental.turbopackRustReactCompileravoids it by running the compiler natively inside Turbopack, and then the Babel plugin is not needed at all. - That Rust option requires
reactCompilerto already be enabled and throws under webpack. compilationMode: 'annotation'is the safe way to adopt it gradually — nothing is compiled until you add"use memo", and"use no memo"excludes a component that misbehaves.
Example
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
reactCompiler: true,
}
export default nextConfigWhen to use it
- Cut re-renders in a large form or dashboard without adding memoization hooks by hand.
- Adopt the compiler one component at a time using annotation mode and "use memo".
- Recover the build time the Babel transform costs by switching to the Rust port under Turbopack.
- Exclude a component that breaks under compilation using the "use no memo" directive.
Frequently asked questions
Do I still need useMemo and useCallback with the React Compiler on?
Largely no — the compiler memoizes components automatically, which is the point of enabling it. Existing hooks are not errors and can stay, but new manual memoization is mostly redundant. If one component depends on referential identity in a way the compiler changes, opt it out with the "use no memo" directive rather than disabling the compiler.
Why did my builds get slower after enabling reactCompiler?
Because the default implementation runs through Babel, and the docs explicitly warn that development and build compile times increase. Next.js reduces the cost with an SWC pre-pass that only sends files with JSX or Hooks to the compiler. To remove most of the remaining overhead, set experimental.turbopackRustReactCompiler to true and build with Turbopack.
Is the React Compiler enabled by default in Next.js 16?
No. Support became stable in Next.js 16 and the option moved out of experimental, but it stays off by default while build-performance data is gathered across application types. You opt in with `reactCompiler: true` and install babel-plugin-react-compiler.
More examples
Opt-in mode with the "use memo" directive
In annotation mode nothing is compiled until you ask for it, so you can enable the compiler across a large codebase and turn it on one file at a time. The "use memo" directive is a React directive placed at the top of a component or hook body. Its opposite, "use no memo", opts a single component back out — useful when one component relies on identity changes the compiler removes.
// next.config.ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
reactCompiler: {
compilationMode: 'annotation',
},
}
export default nextConfig
// app/page.tsx
export default function Page() {
'use memo'
// ...
}Swapping in the native Rust port under Turbopack
Both flags are required: turbopackRustReactCompiler selects which implementation runs but never enables the compiler on its own. With it set, the compiler executes as native code inside Turbopack rather than through Node.js and Babel, which is the main fix for slower builds after adopting the compiler. You can also drop babel-plugin-react-compiler from package.json. Building with webpack while this is set throws.
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
// Enable the React Compiler
reactCompiler: true,
experimental: {
// Use the Rust port instead of the Babel transform
turbopackRustReactCompiler: true,
},
}
export default nextConfigInstalling the Babel plugin the default path requires
The default (Babel) path will not compile anything without this dev dependency, and the failure looks like the config flag having no effect rather than an obvious missing-module error. Skip this step only if you are enabling experimental.turbopackRustReactCompiler, where the compiler is built into Turbopack.
npm install -D babel-plugin-react-compiler
Discussion