Debugging

[poteto]

Although React Compiler has been in use in production at Meta in many high traffic applications, it is still experimental for open source due to differences in tech stacks, so bugs and errors may happen at runtime in your application.

There are a few broad categories of errors that can occur when you use React Compiler:

• Runtime errors or incorrect behavior because of Rules of React violations that couldn't be caught statically
• Runtime infinite loops and/or over-firing of Effects
• Build-time errors in build pipelines

The compiler can statically detect most cases where it isn't safe to compile a component or hook. For example, the compiler assumes that your code follows the Rules of React, so when it detects that a rule has been broken, it will safely skip over the offending components and hooks and continue compiling other files that are safe. Since React Compiler's current optimizations are applied at the function level (meaning that the compiler only looks at the code inside of a component or hook body), it is safe to selectively optimize some components and hooks and skip over others.

Due to the flexible and dynamic nature of JavaScript however, it's not possible to comprehensively detect all cases. Bugs and undefined behavior such as infinite loops may occur in those cases.

Runtime Errors

Something is throwing an error or not working after compilation

If there's a runtime issue, first try to make the error or bug go away by aggressively opting out any component or hook you think might be related via the "use no memo" directive:

function SuspiciousComponent() {
  "use no memo"; // opts out this component from being compiled by React Compiler
  // ...
}

⚠️ "use no memo"

"use no memo" is a temporary escape hatch that lets you opt-out components and hooks from being compiled by the React Compiler. This directive is not meant to be long lived the same way as eg "use client" is.

When you make the error go away, confirm that removing the opt out directive makes the error come back. Then share a bug report with us (you can try to reduce it to a small repro, or if it's open source code you can also just paste the entire source) using the React Compiler Playground so we can identify and help fix the issue.

My app is hanging or firing an Effect over and over

If your app experiences a bug, infinite loop, or an Effect fires too much, what might be happening is that React Compiler is not memoizing dependencies to hooks in the exact same way that they might have been before. We call this a "correctness" issue, because your app was using the memoized dependency as an input to a hook in order for correct behavior. By default, the compiler will attempt to preserve manual memoization and skip over components from optimization if they don't match up, so in practice this should not happen. If it does, please create a repro in the React Compiler Playground so we can identify and help fix the issue.

Build time errors

Debugging build time errors is most likely going to be specific to your setup. If you experience any issues with the Babel plugin in particular, please file an issue.