[Compiler Bug]: enableFunctionOutlining breaks react-native-reanimated API callbacks

[tjzel]

What kind of issue is this?

• React Compiler core (the JS output is incorrect, or your app works incorrectly after optimization)
• babel-plugin-react-compiler (build issue installing or using the Babel plugin)
• eslint-plugin-react-compiler (build issue installing or using the eslint plugin)
• react-compiler-healthcheck (build issue installing or using the healthcheck script)

Link to repro

https://playground.react.dev/#N4Igzg9grgTgxgUxALhHCA7MAXABAFQRwGEIBbAB0wQzwF5cAKYXDKMgIwRlwF8BKXHQB8uYAB0MuXOix4A1ggCe+CAEkMAEwQAPIbihgEAEW4BLAG4JNANQCGAGygJGjQSMnTpAbQCMAGlwAJkCAZgBdADoyOwpXd1E2Bwd+T1x+AG5JNJgEbFgpJIcsjF4SkF4gA

Repro steps

Current version the Compiler started to transform react-native-reanimated API callbacks too much, breaking the code. I compared it with an older version [email protected] and the problem didn't happen there. It seems to be due to the enableFunctionOutlining feature.

Given the code:

const TestComponent = ({ number }) => {
  const keyToIndex = useDerivedValue(() =>
    [1, 2, 3].map(() => null)
  );

  return null;
};

Compiler changes it to

const TestComponent = (t0) => {
  useDerivedValue(_temp2);
  return null;
};
function _temp() {
  return null;
}
function _temp2() {
  return [1, 2, 3].map(_temp);
}

Note that _temp and _temp2 are extracted outside. It's ok to extract _temp2, the callback of useDerivedValue, it's handled on our side as a part of the support for the Compiler. It's not ok to extract _temp.

The problem lies in the fact that we can (and we do) deduce that _temp2 must be a worklet, but we cannot in general infer if _temp should be a worklet. This leads to _temp not being workletized and causing a runtime error. We also can't workletize it regardless, in some flows it actually shouldn't be a worklet.

To fix it we need to keep all functions defined in a worklet to stay in this worklet.

How often does this bug happen?

Every time

What version of React are you using?

19

What version of React Compiler are you using?

19.0.0-beta-bafa41b-20250307

[josephsavona]

Thanks for posting! I'm just curious, why can't you infer that _temp needs to be a worklet? It's only called from useDerivedValue(), so i'm wondering what specifically makes the inference challenging.

[tjzel]

It's because Reanimated's multithreading APIs aren't symmetrical and because it depends on the Metro bundler in React Native. Let's say we have two files:

// file.js
import {runOnJS} from 'react-native-reanimated';

export function foo(callback) {
  'worklet';
  console.log('scheduling back to JS');
  runOnJS(callback);

  return null;
}

// App.jsx
import {useDerivedValue} from 'react-native-reanimated';
import {myRunOnJS} from './file';

export default function App() {
  const dv = useDerivedValue(() => foo(bar));

  return null;
}

function bar() {
  console.log('received on JS');
}

In here bar has to stay a non-worklet because runOnJS cannot be used with a worklet, and foo invokes runOnJS with bar as an argument.

To infer if bar should be a worklet we must be able to analyze the foo function first. That might not be possible, since the order of parsing files is dictated by Metro. What and what can't you do during the bundling process is a completely different topic.

The design decision about asymmetry, runOnJS not accepting worklets, was made years back for performance reasons. We want to change this approach in react-native-worklets but it's still a long way to go.

[piotrski]

I initially thought this issue could be resolved using the Reanimated's babel plugin, but I it's a bit counterintuitive for the compiler to extract functions for Reanimated only to move them back inside the scope.

A potential improvement would be to allow the "use no memo" directive at the function level, not just the component level. This way, the Reanimated's babel plugin could explicitly mark individual worklet functions with "use no memo", preventing unnecessary extraction.

Alternatively, "use server" and "use worklet" could implicitly act as "use no memo", since functions marked with these directives are already meant to be executed in specific, isolated environments. This would eliminate the need for an additional directive while keeping the behavior more predictable.

[tjzel]

A potential improvement would be to allow the "use no memo" directive at the function level, not just the component level. This way, the Reanimated's babel plugin could explicitly mark individual worklet functions with "use no memo", preventing unnecessary extraction.

Reanimated Babel plugin runs only after the Compiler, since the Compiler works on the pre step (unless that has changed) and the Compiler is required to be the first listed plugin, to be the first executed. We purposefully abstained from doing anything in the pre step to not interfere with the Compiler.

Alternatively, "use server" and "use worklet" could implicitly act as "use no memo", since functions marked with these directives are already meant to be executed in specific, isolated environments. This would eliminate the need for an additional directive while keeping the behavior more predictable.

The community wanted less boilerplate so we added recognizing worklets implicitly so the "worklet" directive could be omitted. On one hand it seems like a fair compromise that when using the Compiler you might need to use the "worklet" but on the other it brings back the boilerplate which the Compiler wants to reduce.

[josephsavona]

Hmm, sorry but I’m not quite following. The restrictions you mentioned, @tjzel, seem related to multi-file ordering. But the outlining transform we’re talking about here is within file. It would seem like you could traverse the file, find useDeferredValue calls, traverse within those to find the call to temp2(), follow that declaration, and then see the call to temp(), follow that declaration, and then add all of those to be treated as worklets. If at any point an invalid API like runOnJs() is called you bail out.

What strikes me in particular is that it’s perfectly reasonable for a developer to write code like this directly, so it seems like it would be nice for reanimated to support this pattern if it’s a helper function in the same file. Is there a concrete problem with that approach?

[tjzel]

The problem is that I can't make any assumptions about the functions used inside the useDerivedValue callback. In OG repro I can for 100% say that _temp2 has to be a worklet, but I cannot make such assumption in general for _temp.

In the example _temp is used as a callback for .map() which means _temp should be a worklet. However, if user used something else than .map(), some custom function defined by him in the other file, I don't know whether _temp should be a worklet or not, since I don't know on what runtime _temp should execute.

[josephsavona]

Sure, but that actually doesn't have anything to do with whether the callback is outlined or not:

// A
useDeferredValue(() => {
  obj.method(() => { ... });
})
// B
useDeferredValue(() => {
  obj.method(someFunction)
})
function someFunction() { ... }

Unless I'm missing something, whether this is safe to turn into a worklet or not is a property of obj.method and (independently) whether the lambda/someFunction are safe to turn into worklets. For example, if either of them calls runOnJs() then it can't be worklet-ized. What you mention above is that for [1,2,3,4].map(...) we know it's safe bc it's Array.prototype.map, but that we can't generalize this for other functions, that's saying that it actually doesn't matter whether it's an inline lambda or not. What matters is the type of the method being invoked.

It might help to have a more specific example to look at, maybe something was lost in trying to distill down the problem for a repro? Because in general the outlining doesn't seem to be the problem re safety of workletizing, if outlining is local to the file.

[tjzel]

// A
useDeferredValue(() => {
  obj.method(() => { ... });
})

In here, if obj.method would run runOnJS with the callback, it would result in an error, since the callback is defined inside a worklet. You can use runOnJS with functions that are only defined outside of worklets. So if the function definition is taken outside of the worklet, we don't know if this was on purpose to be able to do runOnJS or if the Compiler took it out.

[josephsavona]

Ahhhh ok. So Reanimated uses the distinction between inline callbacks vs refs to function declarations to decide what to auto-workletize. In that case I wonder if we can just add some property onto functions that we outline so that Reanimated's plugin can detect that. So in the original example, we could add an annotation onto the FunctionDeclaration node for temp and temp2 to say eg isOutlinedByReactCompiler:true.

Would that work?

[tjzel]

I think it could work. I think the annotation should only be applied to functions outlined from the worklet context - I'm afraid that we'll encountered something that has been outlined and falsely assume that it should be a worklet. I haven't came up for an edge-case where it would manifest but I'm not crossing it out as a possibility.

[tjzel]

Another alternative would be to add some customization to the Compiler. You could expose APIs that other plugins can hook into during the transpilation process. This way Reanimated plugin could mark all worklets with the "worklet" directive before the Compiler transforms the code. i.e. plugins could define preCompiler step which the Compiler would invoke.

[josephsavona]

I'm afraid that we'll encountered something that has been outlined and falsely assume that it should be a worklet

It seems like you could avoid this case by design. Presumably you start from known worker functions, ie callbacks to useDeferredValue. You then traverse into subexpressions, following inline function expressions but excluding reference to named variables. You could slightly amend this to check: is the variable reference to a local function declaration that was marked as outlined by React Compiler? If so, include that function as a root and keep going (maybe even inline it back again!).

Ie if you’re starting from known safe-to-workletize functions, you’ll only reach an outlined function in the case that it was originally inlined. Does that sound like it would work?

Re allowing pre-passes: extensive configuration is part of what make Babel exceedingly frustrating to use, and our design principle is to avoid such configuration as much as possible. Per above it seems like there is a good alternative.

[tjzel]

Yes, that's what we do right now, I just don't know the full extent of the changes the Compiler introduces so I'm trying to play it safe. I couldn't break it with the current version of the online playground so maybe I'm just too careful. I think we can try the approach you are suggesting and circle back on it in the future if there's any trouble.

Re allowing pre-passes: extensive configuration is part of what make Babel exceedingly frustrating to use, and our design principle is to avoid such configuration as much as possible. Per above it seems like there is a good alternative.

I always thought it was the part of the awful documentation 🙈

[josephsavona]

Ok cool, we can add a property to outlined function declarations to make this clear to subsequent passes.