Merge pull request #48078 from software-mansion-labs/kicu/48066-react…

…-compiler

[NO QA] Improve react-compiler developer experience and docs

.gitignore

@@ -140,3 +140,6 @@ web-build/
 
 # Jeykll
 docs/.bundle
+
+# Output of react compiler healthcheck dev script
+react-compiler-output.txt

contributingGuides/REACT_COMPILER.md

@@ -16,10 +16,10 @@ If the CI check fails for your PR, you need to fix the problem. If you're unsure
 
 ## How can I check what exactly prevents file from successful optimization or whether my fix for passing `react-compiler` actually works?
 
-You can run `npm run react-compiler-healthcheck` and examine the output. This command will list the files that failed to compile and provide details on what caused the failures. The output can be extensive, so you may want to write it to a file for easier review:
+You can run a dedicated script: `react-compiler-healthcheck-test` and examine the output. This command will list the files that failed to compile with details on what caused the failures. It will then save this output to `./react-compiler-output.txt` file. Read and examine the output to find what specific error the react-compiler throws.
 
 ```bash
-npm run react-compiler-healthcheck &> output.txt
+npm run react-compiler-healthcheck-test
 ```
 
 ## How to fix a particular problem?
@@ -39,9 +39,14 @@ If you encounter this error, you need to add the `Ref` postfix to the variable n
 
 If you added a modification to `SharedValue`, you'll likely encounter this error. You can ignore this error for now because the current `react-native-reanimated` API is not compatible with `react-compiler` rules. Once [this PR](https://github.com/software-mansion/react-native-reanimated/pull/6312) is merged, we'll rewrite the code to be compatible with `react-compiler`. Until then, you can ignore this error.
 
-### `manual memoization could not be preserved`
+### Existing manual memoization could not be preserved. [...]
+These types of errors usually occur when the calls to `useMemo` that were made manually are too complex for react-compiler to understand. React compiler is still experimental so unfortunately this can happen.
 
-This error usually occurs when a dependency used inside a hook is omitted. This omission creates a memoization that is too complex to optimize automatically. Try including the missing dependencies.
+Some specific cases of this error are described below.
+
+#### The inferred dependencies did not match the manually specified dependencies
+
+This usually happens when a dependency used inside a hook is omitted. Try including the missing dependencies.
 
 Please be aware that `react-compiler` struggles with memoization of nested fields, i. e.:
 
@@ -56,6 +61,27 @@ const selectedQboAccountName = useMemo(() => qboAccountOptions?.find(({id}) => i
 // which is great because it reduces the amount of the duplicated code
 ```
 
+#### This value may be mutated later, which could cause the value to change unexpectedly
+
+This usually happens when the value returned from `useMemo` is later passed to some other function, and `react-compiler` doesn't know if the value will stay stable or be mutated.
+
+```ts
+// ❌ such code triggers the error
+const myResult = useMemo(() => SearchUtils.buildSearchQueryJSON(foobar), [foobar]);
+// [...] some other code
+const betterQuery = Utils.improveQuery(myResult);
+
+// ✅ this code can be compiled successfully
+const {myResult, betterQuery} = useMemo(() => {
+    const result = SearchUtils.buildSearchQueryJSON(foobar);
+
+    return {
+        myResult: result,
+        betterQuery: Utils.improveQuery(result)
+    }
+},[foobar]);
+```
+
 ### `Invalid nesting in program blocks or scopes`
 
 Such error may happen if we have a nested memoization, i. e.:

package.json

@@ -62,6 +62,7 @@
     "setup-https": "mkcert -install && mkcert -cert-file config/webpack/certificate.pem -key-file config/webpack/key.pem dev.new.expensify.com localhost 127.0.0.1",
     "e2e-test-runner-build": "node --max-old-space-size=8192 node_modules/.bin/ncc build tests/e2e/testRunner.ts -o tests/e2e/dist/",
     "react-compiler-healthcheck": "react-compiler-healthcheck --verbose",
+    "react-compiler-healthcheck-test": "react-compiler-healthcheck --verbose &> react-compiler-output.txt",
     "generate-search-parser": "peggy --format es -o src/libs/SearchParser/searchParser.js src/libs/SearchParser/searchParser.peggy ",
     "web:prod": "http-server ./dist --cors"
   },