feat(compiler): improve preserved manual memoization diagnostic\n\nAdd CHANGELOG entry under Unreleased for enhanced forward reference guidance in babel-plugin-react-compiler.

Author: Rithvik914

compiler/CHANGELOG.md

@@ -1,3 +1,9 @@
+## Unreleased
+
+## babel-plugin-react-compiler
+
+* Improve diagnostic for preserved manual memoization when a callback references a later-declared memoized value; the message now includes the dependency name (when available), clarifies declaration order, and suggests moving the declaration earlier.
+
 ## 19.1.0-rc.2 (May 14, 2025)
 
 ## babel-plugin-react-compiler

compiler/packages/babel-plugin-react-compiler/src/Validation/ValidatePreservedManualMemoization.ts

@@ -540,18 +540,25 @@ class Visitor extends ReactiveFunctionVisitor<VisitorState> {
           !this.scopes.has(identifier.scope.id) &&
           !this.prunedScopes.has(identifier.scope.id)
         ) {
+          const depName =
+            identifier.name?.kind === 'named' ? identifier.name.value : null;
           state.errors.pushDiagnostic(
             CompilerDiagnostic.create({
               category: ErrorCategory.PreserveManualMemo,
               reason: 'Existing memoization could not be preserved',
               description: [
                 'React Compiler has skipped optimizing this component because the existing manual memoization could not be preserved. ',
                 'This dependency may be mutated later, which could cause the value to change unexpectedly',
+                depName
+                  ? `. If '${depName}' is defined later in the component (e.g., via useMemo or useCallback), try moving this memoization after the dependency's declaration`
+                  : '',
               ].join(''),
             }).withDetails({
               kind: 'error',
               loc,
-              message: 'This dependency may be modified later',
+              message: depName
+                ? `This dependency may be modified later. If '${depName}' is memoized, ensure it's declared before this hook`
+                : 'This dependency may be modified later',
             }),
           );
         }

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/preserve-memo-validation/error.false-positive-useMemo-overlap-scopes.expect.md

@@ -44,13 +44,13 @@ Found 1 error:
 
 Compilation Skipped: Existing memoization could not be preserved
 
-React Compiler has skipped optimizing this component because the existing manual memoization could not be preserved. This dependency may be mutated later, which could cause the value to change unexpectedly.
+React Compiler has skipped optimizing this component because the existing manual memoization could not be preserved. This dependency may be mutated later, which could cause the value to change unexpectedly. If 'x' is defined later in the component (e.g., via useMemo or useCallback), try moving this memoization after the dependency's declaration.
 
 error.false-positive-useMemo-overlap-scopes.ts:23:9
   21 |   const result = useMemo(() => {
   22 |     return [Math.max(x[1], a)];
 > 23 |   }, [a, x]);
-     |          ^ This dependency may be modified later
+     |          ^ This dependency may be modified later. If 'x' is memoized, ensure it's declared before this hook
   24 |   arrayPush(y, 3);
   25 |   return {result, y};
   26 | }

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/preserve-memo-validation/error.useCallback-references-later-useMemo.expect.md

@@ -0,0 +1,75 @@
+
+## Input
+
+```javascript
+// @validatePreserveExistingMemoizationGuarantees:true
+import {useCallback, useMemo} from 'react';
+
+/**
+ * Issue: When a useCallback references a value from a useMemo that is
+ * declared later in the component, the compiler triggers a false positive
+ * preserve-manual-memoization error.
+ *
+ * The error occurs because the validation checks that dependencies have
+ * completed their scope before the manual memo block starts. However,
+ * when the callback is declared before the useMemo, the useMemo's scope
+ * hasn't completed yet.
+ *
+ * This is a valid pattern in React - declaration order doesn't matter
+ * for the runtime behavior since both are memoized.
+ */
+function Component({value}) {
+  // This callback references `memoizedValue` which is declared later
+  const callback = useCallback(() => {
+    return memoizedValue + 1;
+  }, [memoizedValue]);
+
+  // This useMemo is declared after the callback that uses it
+  const memoizedValue = useMemo(() => {
+    return value * 2;
+  }, [value]);
+
+  return {callback, memoizedValue};
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: Component,
+  params: [{value: 5}],
+};
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access variable before it is declared
+
+`memoizedValue` is accessed before it is declared, which prevents the earlier access from updating when this value changes over time.
+
+error.useCallback-references-later-useMemo.ts:21:6
+  19 |   const callback = useCallback(() => {
+  20 |     return memoizedValue + 1;
+> 21 |   }, [memoizedValue]);
+     |       ^^^^^^^^^^^^^ `memoizedValue` accessed before it is declared
+  22 |
+  23 |   // This useMemo is declared after the callback that uses it
+  24 |   const memoizedValue = useMemo(() => {
+
+error.useCallback-references-later-useMemo.ts:24:2
+  22 |
+  23 |   // This useMemo is declared after the callback that uses it
+> 24 |   const memoizedValue = useMemo(() => {
+     |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+> 25 |     return value * 2;
+     | ^^^^^^^^^^^^^^^^^^^^^
+> 26 |   }, [value]);
+     | ^^^^^^^^^^^^^^^ `memoizedValue` is declared here
+  27 |
+  28 |   return {callback, memoizedValue};
+  29 | }
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/preserve-memo-validation/error.useCallback-references-later-useMemo.ts

@@ -0,0 +1,34 @@
+// @validatePreserveExistingMemoizationGuarantees:true
+import {useCallback, useMemo} from 'react';
+
+/**
+ * Issue: When a useCallback references a value from a useMemo that is
+ * declared later in the component, the compiler triggers a false positive
+ * preserve-manual-memoization error.
+ *
+ * The error occurs because the validation checks that dependencies have
+ * completed their scope before the manual memo block starts. However,
+ * when the callback is declared before the useMemo, the useMemo's scope
+ * hasn't completed yet.
+ *
+ * This is a valid pattern in React - declaration order doesn't matter
+ * for the runtime behavior since both are memoized.
+ */
+function Component({value}) {
+  // This callback references `memoizedValue` which is declared later
+  const callback = useCallback(() => {
+    return memoizedValue + 1;
+  }, [memoizedValue]);
+
+  // This useMemo is declared after the callback that uses it
+  const memoizedValue = useMemo(() => {
+    return value * 2;
+  }, [value]);
+
+  return {callback, memoizedValue};
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: Component,
+  params: [{value: 5}],
+};

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/preserve-memo-validation/useCallback-after-useMemo-declared.expect.md

@@ -0,0 +1,77 @@
+
+## Input
+
+```javascript
+// @validatePreserveExistingMemoizationGuarantees:true
+import {useCallback, useMemo} from 'react';
+
+/**
+ * This is the corrected version where the useMemo is declared before
+ * the useCallback that references it. This should compile without errors.
+ */
+function Component({value}) {
+  // useMemo declared first
+  const memoizedValue = useMemo(() => {
+    return value * 2;
+  }, [value]);
+
+  // useCallback references the memoizedValue declared above
+  const callback = useCallback(() => {
+    return memoizedValue + 1;
+  }, [memoizedValue]);
+
+  return {callback, memoizedValue};
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: Component,
+  params: [{value: 5}],
+};
+
+```
+
+## Code
+
+```javascript
+import { c as _c } from "react/compiler-runtime"; // @validatePreserveExistingMemoizationGuarantees:true
+import { useCallback, useMemo } from "react";
+
+/**
+ * This is the corrected version where the useMemo is declared before
+ * the useCallback that references it. This should compile without errors.
+ */
+function Component(t0) {
+  const $ = _c(5);
+  const { value } = t0;
+
+  const memoizedValue = value * 2;
+  let t1;
+  if ($[0] !== memoizedValue) {
+    t1 = () => memoizedValue + 1;
+    $[0] = memoizedValue;
+    $[1] = t1;
+  } else {
+    t1 = $[1];
+  }
+  const callback = t1;
+  let t2;
+  if ($[2] !== callback || $[3] !== memoizedValue) {
+    t2 = { callback, memoizedValue };
+    $[2] = callback;
+    $[3] = memoizedValue;
+    $[4] = t2;
+  } else {
+    t2 = $[4];
+  }
+  return t2;
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: Component,
+  params: [{ value: 5 }],
+};
+
+```
+      
+### Eval output
+(kind: ok) {"callback":"[[ function params=0 ]]","memoizedValue":10}

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/preserve-memo-validation/useCallback-after-useMemo-declared.ts

@@ -0,0 +1,25 @@
+// @validatePreserveExistingMemoizationGuarantees:true
+import {useCallback, useMemo} from 'react';
+
+/**
+ * This is the corrected version where the useMemo is declared before
+ * the useCallback that references it. This should compile without errors.
+ */
+function Component({value}) {
+  // useMemo declared first
+  const memoizedValue = useMemo(() => {
+    return value * 2;
+  }, [value]);
+
+  // useCallback references the memoizedValue declared above
+  const callback = useCallback(() => {
+    return memoizedValue + 1;
+  }, [memoizedValue]);
+
+  return {callback, memoizedValue};
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: Component,
+  params: [{value: 5}],
+};