· By John Kavanagh

A Measured Rollout of the React Compiler

Photograph of a yellow measuring tape against a dark background.
Image by Immo Wegmann, licensed from Unsplash.

Enabling a compiler plugin is a small configuration change. Deciding whether to leave it enabled is a different job.

A successful build tells us that the build completed. It doesn't tell us which components were compiled, whether the same user tasks still work, or whether the change saved useful work. Those questions need separate evidence. Otherwise, it is remarkably easy to celebrate a configuration file.

React Compiler 1.0 became stable earlier this month. I've put together a small rollout experiment using that exact compiler version and React 19.2.0. It has three builds: an uncompiled control, a narrowly compiled surface, and a rollback with compilation removed again.

The source application, synthetic data, production flags, and profiling instrumentation are the same in all three. Only the compiler's application changes. That gives the comparison somewhere sensible to start.


Choose a Surface with a Known Cost

My example filters 9,000 synthetic names. It performs deliberate extra calculation whilst filtering, then displays a count, a digest of that work, and the first six matches. The artificial workload makes repeated calculation visible without needing a large application or somebody else's customer data.

An unrelated counter lives above the result component. Changing it causes the parent to render again whilst the search term and input data remain unchanged. Another button replaces the data with equal‑valued new objects, and the search field changes the filter's real input.

Those interactions answer different questions. The counter offers reusable work. A new query needs a new result. Replacing the data changes its identity even when the visible names are the same. An optimisation which accidentally ignores either real input would look wonderfully quick until somebody tried to use it.

My recent article on useMemo and useCallback examines those decisions when adding memoisation by hand. This experiment keeps that reasoning and changes who generates the caching code. It doesn't assume that installing a compiler removes the need to understand the inputs.


Make the Compilation Boundary Explicit

For the scoped build, the Babel plugin only runs on files in my src/scoped directory. Within that directory, I use annotation mode:

[
  compiler,
  {
    compilationMode: 'annotation',
    target: '19',
  },
]

The result component opts in:

export function Results({ rows, query }) {
  'use memo';

  const result = filterRows(rows, query);
  return renderResults(result);
}

That short excerpt shows the boundary; my downloadable component contains the actual result markup. A small counter badge in the same file has use no memo and remains excluded. The surrounding application is outside the compiled directory.

React's incremental adoption guidance describes directory scoping, opt‑in annotations, and exclusions. I find a deliberately small first boundary easier to review because I can name what changed and what still needs investigation. A permanent collection of unexplained exclusions would deserve rather less enthusiasm.


Check the Generated Result

My build helper records the compiler's events and retains the transformed source for inspection. The acceptance check expects a successful compilation event for Results, generated compiler‑runtime usage in that component's file, and no successful compilation of the excluded badge.

The control has no compiler events. The rollback bundle must have the same SHA-256 hash as the control. The scoped bundle must differ. These are checks of this small build's expected coverage, not a recommendation to make every application test depend on a particular spelling in generated code.

The distinction matters when performance appears unchanged. Perhaps the component was never in scope. Perhaps the compiler skipped it. Perhaps it was compiled successfully and there was little useful work to save. Timing alone cannot distinguish those explanations.

I also keep the dependency versions and build settings beside the observations. Comparing a development control with a production compiled build would be a very efficient way to measure the wrong thing.


Diagnose a Skipped Component Before excluding It

The lab contains a separate, deliberately invalid adapter which writes to a ref and reads it during rendering. Compiler 1.0 reports a diagnostic for it, and the matching React Hooks lint configuration reports the refs violation.

That adapter is not included in the working application. Its corrected partner renders directly from its input prop; the lint passes and the compiler records a successful compilation. This is a small, inspectable example of a source problem which should be fixed, rather than hidden behind an exclusion and forgotten.

As I explain in my useRef article, a ref is useful for persistent values which do not themselves drive rendering, and for accessing a DOM node at the appropriate time. It isn't an alternative state system which makes render‑time mutation harmless. React's ref lint documentation describes that boundary.

A real integration may have different constraints. Record the actual diagnostic and investigate the library or adapter involved. Don't conclude that an entire dependency is incompatible because one local wrapper breaks React's rules, and don't remove an exclusion merely because the build has stopped complaining.


Run the Same Tasks Before Reading the Timings

Each build starts with the same names and an empty query. The test enters Ellie, changes the unrelated counter six times, replaces the data, and then searches for Maddie. It checks the visible count, first result, calculation digest, and counter value against the other builds.

The query change must produce Maddie's results. Equal‑valued replacement must still leave the interface correct. The excluded badge must update throughout. All three builds must finish in the same visible state, with no browser runtime error.

These assertions don't prove every possible interaction is correct. They do prevent the benchmark from rewarding a result component which has simply stopped responding to changes. Add the awkward tasks from the real surface before widening the rollout: editing, selection, focus, external‑store updates, and any identity‑sensitive integration the application actually uses.


Keep Cold and Repeated Work Separate

My measurement uses React's production profiling build in every mode. The profiler surrounds the result component, and its callback stores samples outside the compiled function. The filtering function remains pure; adding render‑time counters inside it would change the code the compiler has to analyse.

The first render still has to calculate a result. The useful comparison here is the repeated counter update with unchanged inputs. In my recorded runs, the control and rollback repeated that render work, whilst the scoped component reused its generated cache. Changing the query or replacing the input data required fresh work again.

The lab records three trials per build, the cold samples, the repeated‑update samples, and the replacement samples separately. It does not enforce a millisecond threshold. Hardware, browser state, profiling overhead, and other running processes can change those numbers.

React's actualDuration is a measure of the profiled render work associated with a commit. It is not a complete interaction latency or a promise about when pixels reached the display. A sample rounded to zero does not mean the browser performed no work at all.


Exercise the Way Back

The rollback build runs the same correctness tasks and returns to the control's bundle hash. That is a useful local check that removing the compiler scope restores the expected build, without requiring a simultaneous source rewrite.

A production rollback still needs its own release procedure, retained artefacts, and monitoring. My small fixture does not prove that an old browser tab will survive a deployment change or that a feature flag will cover every entry point.

My compiler rollout lab includes the matched builds, explicit coverage checks, diagnostic pair, browser tasks, and raw profiling output generated by each run. It is a separate compiler experiment; my existing render‑cost profiler remains useful for investigating state ownership and manual memoisation.

Start with a surface you can explain. Verify that it was compiled, verify that it still works, measure the task you meant to improve, and keep the rollback boring.

Postscript

November 2026: I built and tested the accompanying experiment this month, using React Compiler 1.0 and React 19.2.0.

Downloadable Resource

  • React Compiler Rollout Evidence Lab

    Compare matched control, scoped‑compiler, and rollback builds; inspect compilation coverage, a ref diagnostic, visible behaviour, and separate profiling samples.

    Download ZIP

Want to find out more?

If you need senior hands‑on support with a complex React or Next.js platform, migration, performance issue, or technical SEO problem, send me the context and I'll tell you where I can help.