The React Compiler in Next.js

A tea list that stops rendering again

The tea shop's order page has a note box and a list of teas. When you type in the box, React renders the form again, and by default every component the form renders, too (When React re-renders shows why). The React Compiler is a build tool from the React team that adds memoization to your components for you: it rewrites each one so it keeps the values, functions and JSX elements it can, and makes each one again only when what it was made from changes. The component itself still runs on every render; a child can be skipped when the parent hands it the same element as last time. The React Compiler, in the React course, shows the code it writes. Next.js has it built in, as one option in next.config.ts.

Here is the page without the compiler. It's a real Next.js 16.4.3 project: it was built with next build, run with next start, and opened in real Chrome, which typed a note. Each part of the page counts its own renders, so you can see what React did.

1"use client";2 3import { useState } from "react";4import TeaList from "./tea-list";5import { useRenderCount } from "./use-render-count";6 7const teas = ["Green tea", "Mint tea", "Lemon tea"];8 9export default function OrderForm() {10  const [note, setNote] = useState("");11  const countRef = useRenderCount();12  return (13    <section>14      <label htmlFor="note">Note</label>15      <input id="note" value={note} onChange={(event) => setNote(event.target.value)} />16      <p>17        OrderForm renders: <span ref={countRef} />18      </p>19      <TeaList teas={teas} />20    </section>21  );22}

app/order-form.tsx starts with "use client", so OrderForm is a Client Component (Client Components). Line 10 keeps the note in state, and line 15's onChange sets it on every change. Line 19 renders TeaList with the teas array from line 7, which is made once, when the file loads, so it's the same array on every render.

Both components call useRenderCount from app/use-render-count.ts. Its Effect, on lines 8 to 11 of that file, has no list of dependencies, so it runs after every render of the component that calls it. Line 9 adds one to the count, and line 10 writes it into the <span> that gets the ref. It touches the refs only inside the Effect, never while rendering, which is what the compiler needs.

Open the Steps tab. Step 1 opened /: both counts say 1. In step 2, Chrome typed Oolong, please into Note, all at once, as one change. OrderForm renders: 2, and TeaList renders: 2. TeaList's props didn't change, but React called it anyway, because OrderForm returned a new <TeaList> element. Now the same page with the compiler on:

1import type { NextConfig } from "next";2 3const nextConfig: NextConfig = {4  /* config options here */5  cacheComponents: true,6  partialPrefetching: true,7  reactCompiler: true,8};9 10export default nextConfig;

Two files changed, and no component did. Line 7 of next.config.ts turns the compiler on, and line 19 of package.json installs its Babel plugin. In the Steps tab, step 2 says OrderForm renders: 2 and TeaList renders: 1. The compiled OrderForm kept the <TeaList> element it made on the first render, because nothing it was made from had changed, and returned that same element. React skips a component whose element is the very same object as last time. No memo anywhere (memo, useMemo and useCallback is what you'd write by hand).

Turning it on in next.config.ts

The compiler is a Babel plugin: a piece of Babel, a tool that rewrites JavaScript as your app is built. It doesn't come with the next package. In an existing app, add it as a dev dependency, a package the build uses but visitors never download:

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

--save-exact writes the exact version, with no ^, so an upgrade of the compiler happens only when you choose it. On October 30, 2026, the latest version was 1.0.0. Then set the option, as line 7 of the last example's next.config.ts does. A new app can start with both: create-next-app asks Would you like to use React Compiler? (the default answer is No), or takes a flag:

npx create-next-app@latest tea-shop --react-compiler

It adds "babel-plugin-react-compiler": "1.0.0" to package.json and reactCompiler: true to next.config.ts, the two changes in the example. Each row is one way to write the option, what it does, and which Next.js has it:

The option became stable in Next.js 16. In Next.js 15 it was experimental.reactCompiler, and older tutorials still show that spelling. Set the option without installing the plugin, and the build stops:

1import type { NextConfig } from "next";2 3const nextConfig: NextConfig = {4  /* config options here */5  cacheComponents: true,6  partialPrefetching: true,7  reactCompiler: true,8};9 10export default nextConfig;

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ... > Build error occurredError: Turbopack build failed with 1 error:./next.config.tsError: Failed to resolve package babel-plugin-react-compiler while attempting to resolve React CompilerReact compiler is enabled in next.config.ts. We attempted to resolve React Compiler relative to the next package. Is babel-plugin-react-compiler installed in your node_modules directory?     at ignore-listed frames

The Terminal tab shows next build stopping on ./next.config.ts: Failed to resolve package babel-plugin-react-compiler while attempting to resolve React Compiler. Next.js looks for the plugin next to its own package, in node_modules, and asks whether it's installed. Install it, and the build passes, as in the last example.

What it costs. Next.js's own compiler, SWC, is written in Rust and is fast. The React Compiler runs through Babel, in JavaScript, so each file it compiles takes more work. Next.js's blog post for version 16 says to expect longer compile times in next dev and next build with the option on, and that it isn't on by default while the team gathers build data from different kinds of apps. Next.js keeps the cost small by giving the compiler only the code that needs it: browser code, after a quick check of each file. The recordings don't measure it: they hide times, which change from run to run.

Next.js 16.3 added an experimental Rust port of the compiler that runs inside Turbopack instead of Babel: experimental: { turbopackRustReactCompiler: true }, next to reactCompiler. Next.js 16.4 made it faster, and it was still marked experimental in 16.4. The recordings use the stable Babel plugin. There's nothing to install for the browser: compiled code imports its cache from react/compiler-runtime, which comes with React 19.

Which code Next.js compiles

next build builds your code twice: once for the browser, and once for the server. The server's copy holds the Server Components and also each Client Component, which renders there to make the first HTML. Next.js 16.4.3 hands the compiler only the browser's copy. This is the rule Turbopack uses to decide, from Next.js's Rust code:

    // bail early: no babel config, no react-compiler, or Rust React Compiler is active (babel has
    // nothing to do).
    if babel_config_path.is_none()
        && (react_compiler_options.is_none()
            || use_rust_react_compiler
            || !builtin_conditions.contains(&WebpackLoaderBuiltinCondition::Browser))
    {
        return Ok(Vec::new());
    }

Read it from the top. With no Babel config file of your own, Next.js adds no Babel step at all when the compiler is off, when the experimental Rust port is on, or when the code isn't being built for the browser: that last line, !builtin_conditions.contains(&WebpackLoaderBuiltinCondition::Browser), is "not for the browser". You can read it in babel.rs, lines 123 to 131. Then three more filters run before a file reaches the compiler:

1. Files in node_modules are skipped (get-config.ts, lines 119 to 126), and so is any build for the server.
2. A quick text check: in the default mode, the file must hold "use memo", a name like useState (use then a capital letter), </ or /> (babel.rs, lines 245 to 257). A file of plain helpers never pays for Babel.
3. The compiler itself then compiles only functions that look like components (a name with a capital first letter) or Hooks (a name that starts with use).

Why leave the server alone? A Server Component renders once for each request, or once during the build, and its result is sent as HTML and the RSC payload. It never renders again in the browser, so there's no second render for a memo cache to save (Server Components in Next.js). The server's copy of a Client Component also renders once per request. The renders that repeat are in the browser, after hydration, when state changes.

You can see it in the recordings. Each one looked for some text in the JavaScript files the page loads, the ones in .next/static/chunks. Every compiled component checks its cache slots against a marker, Symbol.for("react.memo_cache_sentinel"), the value an empty slot holds. Each row is one recording and what its JavaScript held:

React's own code holds the marker in both builds, because React fills new cache slots with it. Only the compiled build holds the compiler's check, ===Symbol.for("react.memo_cache_sentinel"). The names and the minified code around it belong to this build, so don't write tools that depend on them.

Opting out, and opting in

The compiler reads two directives, strings on their own as a function's first line: "use no memo" leaves that function as written, and "use memo" asks for it to be compiled. The React Compiler explains them and when to use each. What Next.js adds is the setting for annotation mode, reactCompiler: { compilationMode: "annotation" }, where only functions with "use memo" are compiled. Here is OrderForm asking for it on line 10:

1"use client";2 3import { useState } from "react";4import TeaList from "./tea-list";5import { useRenderCount } from "./use-render-count";6 7const teas = ["Green tea", "Mint tea", "Lemon tea"];8 9export default function OrderForm() {10  "use memo";11  const [note, setNote] = useState("");12  const countRef = useRenderCount();13  return (14    <section>15      <label htmlFor="note">Note</label>16      <input id="note" value={note} onChange={(event) => setNote(event.target.value)} />17      <p>18        OrderForm renders: <span ref={countRef} />19      </p>20      <TeaList teas={teas} />21    </section>22  );23}24 

Pick each version below and open step 2 in its Steps tab. Before you look, guess which versions keep TeaList at 1:

1"use client";2 3import { useState } from "react";4import TeaList from "./tea-list";5import { useRenderCount } from "./use-render-count";6 7const teas = ["Green tea", "Mint tea", "Lemon tea"];8 9export default function OrderForm() {10  const [note, setNote] = useState("");11  const countRef = useRenderCount();12  return (13    <section>14      <label htmlFor="note">Note</label>15      <input id="note" value={note} onChange={(event) => setNote(event.target.value)} />16      <p>17        OrderForm renders: <span ref={countRef} />18      </p>19      <TeaList teas={teas} />20    </section>21  );22}

Each row is one version: TeaList's count after typing, and whether the page's JavaScript holds the compiler's cache checks.

Look at the "use no memo" row. TeaList is still compiled, and still renders again. The memoization that saved TeaList was never inside TeaList: it was OrderForm keeping the element. Opt OrderForm out, and TeaList renders again on every key. The same goes the other way in annotation mode: asking for OrderForm alone was enough.

Checking the compiler's work

The compiler is quiet. When it can't compile a function, it leaves it as written and moves on, and next build passes either way. So check its work yourself. Each row is one way to check, what you see, and what it tells you:

React DevTools. The compiler runs in next dev too. Open your app in development with the React Developer Tools browser extension, open its Components tab, and look for a Memo ✨ badge next to each name: react.dev describes it as the sign that a component was compiled. (That's from React's documentation and from using it; the recordings here run next start without DevTools.)

ESLint. eslint-config-next, Next.js's ESLint config, turns on the recommended rules of eslint-plugin-react-hooks (version 7.1.1 with eslint-config-next 16.4.3). Since version 7, they include the compiler's own diagnostics, like react-hooks/refs, which point at functions the compiler skips because they break a rule it can see. The same preset also has the general Hooks rules, like react-hooks/exhaustive-deps, which check that your code is correct React whether or not the compiler is on; a report from one of those doesn't mean a component was skipped. Here is a TeaList that counts its renders in a ref while it renders, a broken rule on purpose:

1import { useRef } from "react";2 3export default function TeaList({ teas }: { teas: string[] }) {4  const renders = useRef(0);5  renders.current += 1;6  return (7    <section>8      <h2>Our teas</h2>9      <ul>10        {teas.map((tea) => (11          <li key={tea}>{tea}</li>12        ))}13      </ul>14      <p>TeaList renders: {renders.current}</p>15    </section>16  );17}

$ npx eslint ./my-app/app/tea-list.tsx   5:3   error  Error: Cannot access refs during render React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef). /my-app/app/tea-list.tsx:5:3  3 | export default function TeaList({ teas }: { teas: string[] }) {  4 |   const renders = useRef(0);> 5 |   renders.current += 1;    |   ^^^^^^^^^^^^^^^ Cannot access ref value during render  6 |   return (  7 |     <section>  8 |       <h2>Our teas</h2>  react-hooks/refs   5:3   error  Error: Cannot access refs during render React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef). /my-app/app/tea-list.tsx:5:3  3 | export default function TeaList({ teas }: { teas: string[] }) {  4 |   const renders = useRef(0);> 5 |   renders.current += 1;    |   ^^^^^^^^^^^^^^^ Cannot update ref during render  6 |   return (  7 |     <section>  8 |       <h2>Our teas</h2>        react-hooks/refs  14:28  error  Error: Cannot access refs during render React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef). /my-app/app/tea-list.tsx:14:28  12 |         ))}  13 |       </ul>> 14 |       <p>TeaList renders: {renders.current}</p>     |                            ^^^^^^^^^^^^^^^ Cannot access ref value during render  15 |     </section>  16 |   );  17 | }                                        react-hooks/refs ✖ 3 problems (3 errors, 0 warnings) $ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /└ ○ /_not-found ○  (Static)  prerendered as static content

The example adds eslint.config.mjs, and ESLint 9 with eslint-config-next in package.json, as create-next-app writes them when you pick ESLint. The Terminal tab shows npx eslint . first. Line 5 of app/tea-list.tsx changes renders.current while rendering, and line 14 reads it: Cannot access refs during render, three errors from react-hooks/refs (two of them on line 5, one for reading and one for writing). Then next build passes: since Next.js 16 it doesn't run ESLint, and the compiler simply left this TeaList as written. Run ESLint in your editor and before every build, for example in CI. With the shop's own useRenderCount, which touches refs only in an Effect, ESLint printed nothing at all:

1import { useEffect, useRef } from "react";2 3// Counts the renders of the component that calls it. After each render,4// it writes the count into the element that gets the returned ref.5export function useRenderCount() {6  const elementRef = useRef<HTMLSpanElement>(null);7  const renders = useRef(0);8  useEffect(() => {9    renders.current += 1;10    if (elementRef.current) elementRef.current.textContent = String(renders.current);11  });12  return elementRef;13}

$ npx eslint .  $ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /└ ○ /_not-found ○  (Static)  prerendered as static content

The built JavaScript. The table of what the page's JavaScript held is a search of the files in .next/static/chunks. A common tip says to search them for react/compiler-runtime, the module compiled code imports. In this production build, the text compiler-runtime wasn't there at all: the bundle didn't keep the import's name. The compiler's check was there, though how it looks is this build's detail, not something React promises. For a check you can rely on, use DevTools.

Measure. Fewer renders are only a win where renders were slow. Measure a slow interaction before and after with the React DevTools profiler (Profiling React apps), and watch how quickly the page answers clicks, its INP, as Core Web Vitals shows.

Turning it on in the tea shop

The compiler keeps only what didn't change. In this version, the teas live in OrderForm's state, and a button adds one:

1"use client";2 3import { useState } from "react";4import TeaList from "./tea-list";5import { useRenderCount } from "./use-render-count";6 7export default function OrderForm() {8  const [note, setNote] = useState("");9  const [teas, setTeas] = useState(["Green tea", "Mint tea", "Lemon tea"]);10  const countRef = useRenderCount();11  return (12    <section>13      <label htmlFor="note">Note</label>14      <input id="note" value={note} onChange={(event) => setNote(event.target.value)} />15      <button type="button" onClick={() => setTeas([...teas, "Oolong tea"])}>16        Add Oolong tea17      </button>18      <p>19        OrderForm renders: <span ref={countRef} />20      </p>21      <TeaList teas={teas} />22    </section>23  );24}

Line 9 keeps the teas in state, and line 15's button gives setTeas a new array with Oolong tea at the end. In the Steps tab, step 2 is the note: TeaList renders: 1, as before. Step 3 is the click on Add Oolong tea: OrderForm renders: 3, TeaList renders: 2, and the list shows Oolong tea. teas was a new array, so the kept element was out of date and OrderForm made a new one. That's the whole deal: you write plain code, and the compiled OrderForm reuses the element it kept until teas, what it was made from, changes.

For an app that already works, The React Compiler walks through adopting it step by step: lint first, start with a few components, test and measure, then turn it on everywhere. In Next.js, those steps map to three settings you've now seen recorded: eslint-config-next for the lint, compilationMode: "annotation" with "use memo" to start small, and reactCompiler: true with an exact plugin version to finish.

Sort each piece of the shop's code: does Next.js compile it with reactCompiler: true, in the default mode?

Common mix-ups

• "The compiler runs in the visitor's browser." No. It runs when Next.js builds your code, in next build and in next dev. The browser runs the code it wrote.
• "Turning it on compiles my Server Components too." No. Next.js 16.4.3 gives the compiler only the code it builds for the browser. Server Components render once per request or build, so there's nothing to keep between renders.
• "reactCompiler: true is all it takes." No. Without babel-plugin-react-compiler installed, the build stops with Failed to resolve package babel-plugin-react-compiler.
• "If the compiler can't handle a component, the build tells me." No. It leaves that component as written, and the build passes. ESLint's compiler rules, like react-hooks/refs, point at it, and next build doesn't run ESLint.
• ""use no memo" in TeaList makes TeaList render on every key." No. The kept element lives in OrderForm, so React still skips TeaList. Opt out the parent to change that.
• "Search the built files for react/compiler-runtime to check." Not in this production build: the module's name wasn't in the page's JavaScript. The compiler's check of its cache slots was.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

"use client";

import { useState } from "react";
import TeaList from "./tea-list";
import { useRenderCount } from "./use-render-count";

const teas = ["Green tea", "Mint tea", "Lemon tea"];

export default function OrderForm() {
  const [note, setNote] = useState("");
  const countRef = useRenderCount();
  return (
    <section>
      <label htmlFor="note">Note</label>
      <input id="note" value={note} onChange={(event) => setNote(event.target.value)} />
      <p>
        OrderForm renders: <span ref={countRef} />
      </p>
      <TeaList teas={teas} />
    </section>
  );
}

import { useRenderCount } from "./use-render-count";

export default function TeaList({ teas }: { teas: string[] }) {
  "use no memo";
  const countRef = useRenderCount();
  return (
    <section>
      <h2>Our teas</h2>
      <ul>
        {teas.map((tea) => (
          <li key={tea}>{tea}</li>
        ))}
      </ul>
      <p>
        TeaList renders: <span ref={countRef} />
      </p>
    </section>
  );
}

"use client";

import { useState } from "react";
import TeaList from "./tea-list";
import { useRenderCount } from "./use-render-count";

export default function OrderForm() {
  const [note, setNote] = useState("");
  const countRef = useRenderCount();
  const teas = ["Green tea", "Mint tea", "Lemon tea"];
  return (
    <section>
      <label htmlFor="note">Note</label>
      <input id="note" value={note} onChange={(event) => setNote(event.target.value)} />
      <p>
        OrderForm renders: <span ref={countRef} />
      </p>
      <TeaList teas={teas} />
    </section>
  );
}

import { useRef } from "react";

export default function TeaList({ teas }: { teas: string[] }) {
  const renders = useRef(0);
  renders.current += 1;
  return (
    <section>
      <h2>Our teas</h2>
      <ul>
        {teas.map((tea) => (
          <li key={tea}>{tea}</li>
        ))}
      </ul>
      <p>TeaList renders: {renders.current}</p>
    </section>
  );
}

const countRef = useRenderCount();
// …
<p>
  TeaList renders: <span ref={countRef} />
</p>

Check your understanding

Key takeaways

• Install babel-plugin-react-compiler and set reactCompiler: true in next.config.ts. It's stable since Next.js 16 (it was experimental.reactCompiler in 15) and off by default.
• Next.js 16.4.3 runs it through Babel on Client Component code built for the browser, after a quick check of each file. Server Components, the server's copy of Client Components, and node_modules are left as written.
• A compiled component still runs on every render, but reuses the values, functions and JSX elements it kept until what each was made from changes. A reused element lets React skip that child, with no memo.
• "use no memo" opts one function out; annotation mode compiles only functions with "use memo". The memoization that skips a child lives in its parent.
• The build passes even when the compiler skips code. Check with React DevTools' Memo ✨ badge, ESLint's compiler rules like react-hooks/refs (run them yourself; next build doesn't), and measurements.

Coming next: Accessibility. What Next.js does for screen reader and keyboard users when the page changes, and what's left for you to do.