React Compiler in production: how to roll it out safely

How to enable React Compiler in an existing React or Next.js app: lint rules, gradual rollout, testing effects and what to do with useMemo.

Crest Design
React logo with a compiler and memoisation theme

React Compiler is a build-time tool that adds memoisation to your components and hooks automatically, so your team writes far less useMemo, useCallback and React.memo by hand. It reached a stable 1.0 release in October 2025, and Next.js 16 made it a stable, top-level config option. At the time of writing (November 2026), the question for most teams is no longer whether it works, but how to switch it on in an existing app without surprises.

The short answer: turn on the compiler-aware lint rules first, enable the compiler for a slice of your code, test anything that depends on effects, then widen the rollout. This guide walks through each step for Next.js and plain React projects.

What the compiler actually does

React re-renders a component when its state, props or context change, and its children usually re-render with it. Teams have traditionally limited wasted work with manual memoisation, which is easy to get wrong and tedious to maintain. The compiler analyses your components at build time and inserts that memoisation for you. The React team points out it can also memoise in places manual code can't, such as values calculated after an early return.

It relies on your code following the Rules of React: components are pure during render, props and state are treated as immutable, and hooks are called unconditionally. According to the React docs, when the compiler finds code that might break these rules it skips optimising it rather than risk changing behaviour.

On results, the React team reported that on the Meta Quest Store, initial loads and cross-page navigations improved by up to 12%, and certain interactions were more than 2.5 times faster, with memory use neutral. They also say "your mileage may vary", so treat those numbers as an example, not a forecast for your app.

Version support at the time of writing

Setup Status
React 19 Supported directly
React 17 and 18 Supported, with a minimum target set in the compiler config and the react-compiler-runtime package installed
Next.js 16 and later Stable top-level reactCompiler option
Next.js 15.3.1 to 15.x Available under experimental.reactCompiler; 15.3.1 is the minimum the React team recommends for build performance
Expo SDK 54 and later Enabled by default

Step 1: switch on the lint rules before the compiler

The compiler-powered lint rules ship in eslint-plugin-react-hooks, in its recommended and recommended-latest presets. The React team recommends recommended, and the linter works without the compiler installed. If you previously added eslint-plugin-react-compiler, remove it and use the latest eslint-plugin-react-hooks instead.

Run the linter across the whole codebase before you change any build settings. Rules such as set-state-in-render, set-state-in-effect and refs flag patterns that cause render loops, expensive effects or unsafe ref access. Each warning is either a component the compiler will probably skip or a spot where behaviour could change, so the warning list doubles as your rollout to-do list.

Step 2: enable it, gradually if you need to

In Next.js, install the plugin as a dev dependency with npm install -D babel-plugin-react-compiler, then set reactCompiler: true in next.config.ts. Next.js uses its own SWC step so the compiler only runs on relevant files, such as those containing JSX or hooks. The Next.js docs say builds can still be slightly slower than without the compiler, but the impact is small and localised.

For a large or older app, start smaller:

  • Annotation mode (Next.js or Babel): set reactCompiler: { compilationMode: 'annotation' } and only components or hooks that start with the 'use memo' directive are compiled. Good for proving value on a few heavy screens first.
  • Opt-out directive: 'use no memo' at the top of a function excludes it, which is useful for parking one problem component while the rest of the app is compiled.
  • Directory rollout (Babel projects): use Babel overrides with a test pattern so only folders such as src/features are compiled, then add folders as they pass testing.
  • Runtime gating (Babel projects): the gating option wraps compiled code in a feature-flag check, so you can roll out to a share of users and compare real-world metrics.

Next.js also exposes enablePreserveExistingMemoizationGuarantees under reactCompiler.environment. Its docs note that defaults can differ between compiler versions and advise setting it explicitly for consistent behaviour.

Finally, pin the version. The React team says future releases may change how memoisation is applied, which can occasionally affect when useEffect fires. If your test coverage is thin, they recommend an exact version such as 1.0.0 rather than a range, and upgrading deliberately.

Step 3: test the code that depends on memoisation

The React debugging guide says problems usually appear where an app depends on specific values being memoised to work properly. The compiler's memoisation can differ from your hand-written version, which can show up as effects firing too often, infinite loops or missing updates. Focus your testing on:

  • Effects whose dependency arrays contain objects, arrays or functions that relied on stable references.
  • Analytics or tracking calls fired from effects, where an extra run means duplicate events.
  • Data fetching in effects, where an extra run means extra API calls.
  • Third-party widgets such as maps, carousels and chat embeds that initialise in an effect.
  • Logic that compares references to decide whether something changed.

React DevTools marks compiled components with a ✨ badge, which is the quickest way to confirm what was optimised. If a component misbehaves, add 'use no memo' to isolate it. If the bug disappears, the React docs suggest you are most likely looking at a Rules of React violation to fix; once fixed, remove the directive and check the badge returns. End-to-end tests on your key journeys (sign-up, checkout, contact forms) are the best safety net here.

What to do with existing useMemo and useCallback

The React team's guidance is practical. In new code, rely on the compiler and reach for useMemo or useCallback only when you need precise control, for example when a memoised value is an effect dependency and must not change. In existing code, either leave manual memoisation in place or test carefully before removing it, because removing it can change the compiler's output. There is no need for a big clean-up sprint.

Lint first, compile a slice, test your effects, then widen the rollout.

Is it worth it for a marketing site?

The compiler helps when client components re-render. If most of your site is Server Components with small interactive pieces, expect smaller differences; the bigger wins tend to be in dashboards, product configurators, filterable listings and long forms. It also doesn't replace other performance work: image sizing, bundle size, third-party scripts and server response time still need their own attention. For many teams the main benefit is simpler code, because developers stop hand-tuning memoisation.

Frequently asked questions

Do I need React 19 to use React Compiler?

No. It supports React 17 and later. On React 17 or 18 you set a minimum target in the compiler config and add the react-compiler-runtime package.

Will it slow down my Next.js builds?

Slightly, in some cases. Next.js only applies the compiler to relevant files to keep the cost small, and its docs describe the impact as small and localised.

Can I turn it off for a single component?

Yes. Add the 'use no memo' directive at the top of the component or hook.

Should we delete all our useMemo calls?

Not in one go. Leave existing memoisation unless you have tests covering the behaviour, and stop adding it by default in new code.

Need help with a React or Next.js upgrade?

We plan and test framework upgrades, including compiler rollouts, as part of our React development and Next.js development services. You can see an example in our React front end and Node.js API for a startup incubator, and read more in React vs Next.js and React 19.3 in practice. If you'd like a second pair of eyes on your rollout, get in touch.

Sources: React Compiler v1.0 (react.dev), Incremental adoption (react.dev), Debugging and troubleshooting (react.dev), reactCompiler (Next.js docs)

(over to you)

Planning a build like this?

Tell us what you're building and we'll come back with ideas and next steps.