[compiler] Detect known incompatible libraries #34027

josephsavona · 2025-07-28T22:20:58Z

A few libraries are known to be incompatible with memoization, whether manually via useMemo() or via React Compiler. This puts us in a tricky situation. On the one hand, we understand that these libraries were developed prior to our documenting the Rules of React, and their designs were the result of trying to deliver a great experience for their users and balance multiple priorities around DX, performance, etc. At the same time, using these libraries with memoization — and in particular with automatic memoization via React Compiler — can break apps by causing the components using these APIs not to update. Concretely, the APIs have in common that they return a function which returns different values over time, but where the function itself does not change. Memoizing the result on the identity of the function will mean that the value never changes. Developers reasonable interpret this as "React Compiler broke my code".

Of course, the best solution is to work with developers of these libraries to address the root cause, and we're doing that. We've previously discussed this situation with both of the respective libraries:

In the meantime we need to make sure that React Compiler can work out of the box as much as possible. This means teaching it about popular libraries that cannot be memoized. We also can't silently skip compilation, as this confuses users, so we need these error messages to be visible to users. To that end, this PR adds:

A flag to mark functions/hooks as incompatible
Validation against use of such functions
A default type provider to provide declarations for two known-incompatible libraries

Note that Mobx is also incompatible, but the observable() function is called outside of the component itself, so the compiler cannot currently detect it. We may add validation for such APIs in the future.

Again, we really empathize with the developers of these libraries. We've tried to word the error message non-judgementally, because we get that it's hard! We're open to feedback about the error message, please let us know.

Stack created with Sapling. Best reviewed with ReviewStack.

josephsavona · 2025-07-28T22:24:59Z

...compiler/src/__tests__/fixtures/compiler/error.invalid-known-incompatible-function.expect.md

+Error: Use of incompatible library
+
+This API returns functions which cannot be memoized without leading to stale UI. To prevent this, by default React Compiler will skip memoizing this component/hook. However, you may see issues if values from this API are passed to other componets/hooks that are memoized.
+
+error.invalid-known-incompatible-function.ts:4:15
+  2 |
+  3 | function Component() {
+> 4 |   const data = knownIncompatible();
+    |                ^^^^^^^^^^^^^^^^^ useKnownIncompatible is known to be incompatible
+  5 |   return <div>Error</div>;
+  6 | }
+  7 |
+```


Example error message

poteto · 2025-07-29T14:27:14Z

compiler/packages/babel-plugin-react-compiler/src/Inference/InferMutationAliasingEffects.ts

+    const errors = new CompilerError();
+    errors.pushDiagnostic(
+      CompilerDiagnostic.create({
+        severity: ErrorSeverity.InvalidReact,


maybe a new category?

We added the `@enableTreatRefLikeIdentifiersAsRefs` feature a while back but never enabled it. Since then we've continued to see examples that motivate this mode, so here we're fixing it up to prepare to enable by default. It now works as follows: * If we find a property load or property store where both a) the object's name is ref-like (`ref` or `-Ref`) and b) the property is `current`, we infer the object itself as a ref and the value of the property as a ref value. Originally the feature only detected property loads, not stores. * Inferred refs are not considered stable (this is a change from the original implementation). The only way to get a stable ref is by calling `useRef()`. We've seen issues with assuming refs are stable. With this change, cases like the following now correctly error: ```js function Foo(props) { const fooRef = props.fooRef; fooRef.current = true; ^^^^^^^^^^^^^^ cannot modify ref in render } ``` --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34000). * #34027 * #34026 * #34025 * #34024 * #34005 * #34006 * #34004 * #34003 * __->__ #34000

Improves the error message for ValidateNoRefAccessInRender, using the new diagnostic type as well as providing a longer but succinct summary of what refs are for and why they're unsafe to access in render. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34003). * #34027 * #34026 * #34025 * #34024 * #34005 * #34006 * #34004 * __->__ #34003

We added the `@enableTreatRefLikeIdentifiersAsRefs` feature a while back but never enabled it. Since then we've continued to see examples that motivate this mode, so here we're fixing it up to prepare to enable by default. It now works as follows: * If we find a property load or property store where both a) the object's name is ref-like (`ref` or `-Ref`) and b) the property is `current`, we infer the object itself as a ref and the value of the property as a ref value. Originally the feature only detected property loads, not stores. * Inferred refs are not considered stable (this is a change from the original implementation). The only way to get a stable ref is by calling `useRef()`. We've seen issues with assuming refs are stable. With this change, cases like the following now correctly error: ```js function Foo(props) { const fooRef = props.fooRef; fooRef.current = true; ^^^^^^^^^^^^^^ cannot modify ref in render } ``` --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34000). * #34027 * #34026 * #34025 * #34024 * #34005 * #34006 * #34004 * #34003 * __->__ #34000 DiffTrain build for [85bbe39](85bbe39)

…p) (#34004) Two related changes: * ValidateNoRefAccessInRender now allows the mergeRefs pattern, ie a function that aggregates multiple refs into a new ref. This is the main case where we have seen false positive no-ref-in-render errors. * Behind `@enableTreatRefLikeIdentifiersAsRefs`, we infer values passed as the `ref` prop to some JSX as refs. The second change is potentially helpful for situations such as ```js function Component({ref: parentRef}) { const childRef = useRef(null); const mergedRef = mergeRefs(parentRef, childRef); useEffect(() => { // generally accesses childRef, not mergedRef }, []); return <Foo ref={mergedRef} />; } ``` Ie where you create a merged ref but don't access its `.current` property. Without inferring `ref` props as refs, we'd fail to allow this merge refs case. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34004). * #34027 * #34026 * #34025 * #34024 * #34005 * #34006 * __->__ #34004

We infer render helpers as functions whose result is immediately interpolated into jsx. This is a very conservative approximation, to help with common cases like `<Foo>{props.renderItem(ref)}</Foo>`. The idea is similar to hooks that it's ultimately on the developer to catch ref-in-render validations (and the runtime detects them too), so we can be a bit more relaxed since there are valid reasons to use this pattern. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34006). * #34027 * #34026 * #34025 * #34024 * #34005 * __->__ #34006 * #34004

Improves the error message for ValidateNoRefAccessInRender, using the new diagnostic type as well as providing a longer but succinct summary of what refs are for and why they're unsafe to access in render. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34003). * #34027 * #34026 * #34025 * #34024 * #34005 * #34006 * #34004 * __->__ #34003 DiffTrain build for [79dc706](79dc706)

…p) (#34004) Two related changes: * ValidateNoRefAccessInRender now allows the mergeRefs pattern, ie a function that aggregates multiple refs into a new ref. This is the main case where we have seen false positive no-ref-in-render errors. * Behind `@enableTreatRefLikeIdentifiersAsRefs`, we infer values passed as the `ref` prop to some JSX as refs. The second change is potentially helpful for situations such as ```js function Component({ref: parentRef}) { const childRef = useRef(null); const mergedRef = mergeRefs(parentRef, childRef); useEffect(() => { // generally accesses childRef, not mergedRef }, []); return <Foo ref={mergedRef} />; } ``` Ie where you create a merged ref but don't access its `.current` property. Without inferring `ref` props as refs, we'd fail to allow this merge refs case. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34004). * #34027 * #34026 * #34025 * #34024 * #34005 * #34006 * __->__ #34004 DiffTrain build for [1d7e942](1d7e942)

`@enableTreatRefLikeIdentifiersAsRefs` is now on by default. I made one small fix to the render helper logic as part of this, uncovered by including more tests. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34005). * #34027 * #34026 * #34025 * #34024 * __->__ #34005

Fixes #30782 When developers do an `if (ref.current == null)` guard for lazy ref initialization, the "safe" blocks should extend up to the if's fallthrough. Previously we only allowed writing to the ref in the if consequent, but this meant that you couldn't use a ternary, logical, etc in the if body. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34024). * #34027 * #34026 * #34025 * __->__ #34024

…zer (#34025) Per title, disallow ref access in `useState()` initializer function, `useReducer()` reducer, and `useReducer()` init function. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34025). * #34027 * #34026 * __->__ #34025

…mutated (#34026) Allows assigning a ref-accessing function to an object so long as that object is not subsequently transitively mutated. We should likely rewrite the ref validation to use the new mutation/aliasing effects, which would provide a more consistent behavior across instruction types and require fewer special cases like this. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34026). * #34027 * __->__ #34026

`@enableTreatRefLikeIdentifiersAsRefs` is now on by default. I made one small fix to the render helper logic as part of this, uncovered by including more tests. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34005). * #34027 * #34026 * #34025 * #34024 * __->__ #34005 DiffTrain build for [6891dcb](6891dcb)

…zer (#34025) Per title, disallow ref access in `useState()` initializer function, `useReducer()` reducer, and `useReducer()` init function. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34025). * #34027 * #34026 * __->__ #34025 DiffTrain build for [c2326b1](c2326b1)

…mutated (#34026) Allows assigning a ref-accessing function to an object so long as that object is not subsequently transitively mutated. We should likely rewrite the ref validation to use the new mutation/aliasing effects, which would provide a more consistent behavior across instruction types and require fewer special cases like this. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34026). * #34027 * __->__ #34026 DiffTrain build for [04a7a61](04a7a61)

A few libraries are known to be incompatible with memoization, whether manually via `useMemo()` or via React Compiler. This puts us in a tricky situation. On the one hand, we understand that these libraries were developed prior to our documenting the [Rules of React](https://react.dev/reference/rules), and their designs were the result of trying to deliver a great experience for their users and balance multiple priorities around DX, performance, etc. At the same time, using these libraries with memoization — and in particular with automatic memoization via React Compiler — can break apps by causing the components using these APIs not to update. Concretely, the APIs have in common that they return a function which returns different values over time, but where the function itself does not change. Memoizing the result on the identity of the function will mean that the value never changes. Developers reasonable interpret this as "React Compiler broke my code". Of course, the best solution is to work with developers of these libraries to address the root cause, and we're doing that. We've previously discussed this situation with both of the respective libraries: * React Hook Form: react-hook-form/react-hook-form#11910 (comment) * TanStack Table: #33057 (comment) and TanStack/table#5567 In the meantime we need to make sure that React Compiler can work out of the box as much as possible. This means teaching it about popular libraries that cannot be memoized. We also can't silently skip compilation, as this confuses users, so we need these error messages to be visible to users. To that end, this PR adds: * A flag to mark functions/hooks as incompatible * Validation against use of such functions * A default type provider to provide declarations for two known-incompatible libraries Note that Mobx is also incompatible, but the `observable()` function is called outside of the component itself, so the compiler cannot currently detect it. We may add validation for such APIs in the future. Again, we really empathize with the developers of these libraries. We've tried to word the error message non-judgementally, because we get that it's hard! We're open to feedback about the error message, please let us know.

react-sizebot · 2025-07-29T19:25:47Z

Comparing: 04a7a61...ec6ecf0

Critical size changes

Includes critical production bundles, as well as any change greater than 2%:

Name	+/-	Base	Current	+/- gzip	Base gzip	Current gzip
oss-stable/react-dom/cjs/react-dom.production.js	=	6.68 kB	6.68 kB	=	1.83 kB	1.83 kB
oss-stable/react-dom/cjs/react-dom-client.production.js	=	530.04 kB	530.04 kB	=	93.63 kB	93.63 kB
oss-experimental/react-dom/cjs/react-dom.production.js	=	6.69 kB	6.69 kB	=	1.83 kB	1.83 kB
oss-experimental/react-dom/cjs/react-dom-client.production.js	=	654.48 kB	654.48 kB	=	115.34 kB	115.34 kB
facebook-www/ReactDOM-prod.classic.js	=	674.42 kB	674.42 kB	=	118.68 kB	118.68 kB
facebook-www/ReactDOM-prod.modern.js	=	664.84 kB	664.84 kB	=	117.02 kB	117.02 kB

Significant size changes

Includes any change greater than 0.2%:

(No significant changes)

Generated by 🚫 dangerJS against ec6ecf0

--- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34044). * #34027 * __->__ #34044

--- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34044). * #34027 * __->__ #34044 DiffTrain build for [88b40f6](88b40f6)

…mutated (facebook#34026) Allows assigning a ref-accessing function to an object so long as that object is not subsequently transitively mutated. We should likely rewrite the ref validation to use the new mutation/aliasing effects, which would provide a more consistent behavior across instruction types and require fewer special cases like this. --- [//]: # (BEGIN SAPLING FOOTER) Stack created with [Sapling](https://sapling-scm.com). Best reviewed with [ReviewStack](https://reviewstack.dev/facebook/react/pull/34026). * facebook#34027 * __->__ facebook#34026 DiffTrain build for [04a7a61](facebook@04a7a61)

facebook-github-bot added the CLA Signed label Jul 28, 2025

github-actions bot added the React Core Team Opened by a member of the React Core Team label Jul 28, 2025

josephsavona commented Jul 28, 2025

View reviewed changes

josephsavona force-pushed the pr34027 branch from cd67ca7 to ed579dc Compare July 28, 2025 22:30

poteto approved these changes Jul 29, 2025

View reviewed changes

josephsavona force-pushed the pr34027 branch from ed579dc to 0315442 Compare July 29, 2025 17:02

josephsavona force-pushed the pr34027 branch from 0315442 to 1b4f28e Compare July 29, 2025 17:05

josephsavona force-pushed the pr34027 branch from 1b4f28e to 71a49d5 Compare July 29, 2025 17:47

josephsavona force-pushed the pr34027 branch from 71a49d5 to dc15a54 Compare July 29, 2025 17:52

josephsavona force-pushed the pr34027 branch from dc15a54 to 077316f Compare July 29, 2025 17:55

josephsavona force-pushed the pr34027 branch from 077316f to cfaef1c Compare July 29, 2025 17:57

josephsavona force-pushed the pr34027 branch from cfaef1c to a2d4dd6 Compare July 29, 2025 17:59

josephsavona force-pushed the pr34027 branch from a2d4dd6 to c15116e Compare July 29, 2025 18:43

josephsavona mentioned this pull request Jul 29, 2025

Enable ref validation in linter #34044

Merged

josephsavona added 2 commits July 29, 2025 12:22

Enable ref validation in linter

7d696dc

josephsavona force-pushed the pr34027 branch from c15116e to ec6ecf0 Compare July 29, 2025 19:22

kushxg mentioned this pull request Aug 1, 2025

Mirror of upstream PR #34027 kushxg/react-mirror#260

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[compiler] Detect known incompatible libraries #34027

[compiler] Detect known incompatible libraries #34027

josephsavona commented Jul 28, 2025 •

edited

Loading

Uh oh!

josephsavona Jul 28, 2025

Uh oh!

poteto Jul 29, 2025

Uh oh!

react-sizebot commented Jul 29, 2025

Uh oh!

Uh oh!

[compiler] Detect known incompatible libraries #34027

Are you sure you want to change the base?

[compiler] Detect known incompatible libraries #34027

Conversation

josephsavona commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

josephsavona Jul 28, 2025

Choose a reason for hiding this comment

Uh oh!

poteto Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

react-sizebot commented Jul 29, 2025

Critical size changes

Significant size changes

Uh oh!

Uh oh!

josephsavona commented Jul 28, 2025 •

edited

Loading