Reanimated, useSharedValue, and third-party defined types in the Compiler

[tjzel]

Hi, first of all, I want to thank you for your amazing effort on the React Compiler. It required very little work to enable it in our example apps for Reanimated testing purposes and it worked like a charm.

As agreed upon, I want to move our previous discussions here, sum it up, and present our point of view, as Reanimated maintainers, in a more organized manner. Reanimated works across both native and web platforms, but for simplicity, I'll stick mostly to the native cases here.

Summary

Here is a brief summary in a tl;dr format.
Currently, the Compiler considers the API of useSharedValue as breaking the rules of React. However, after our analysis of useSharedValue, we consider that it does not do so. There are certain values stemming from the implicit use of getters and setters in its implementation, and while it might seem that Shared Values are mutable objects, they are not; they don't affect renders and depending on them during render is a bad practice, discouraged by the Reanimated team.

What is the issue?

With the introduction of the React Compiler, the API utilized by Shared Values is considered as an error, since the Compiler falsely detects illegal mutations. Take a look at the following example:

export default function Component() {
  const width = useSharedValue(100);

  const tap = Gesture.Tap().onFinalize(() => {
    'worklet';
    width.value += 10;
    // Error: Mutating a value returned from a function whose return value should not be mutated.
    // However, `width.value` actually has a setter.
  });

  return (
    <View style={styles.container}>
      <GestureDetector gesture={tap}>
        {/* Note that the whole Shared Value is passed to the Animated.View, not just `.value`. */}
        <Animated.View style={[styles.staticBox, { width }]} /> 
      </GestureDetector>
    </View>
  );
}

However, this kind of code forms the backbone of how the Reanimated API works. We'd like to explain why, in our opinion, this pattern should be allowed and how it could possibly be implemented.

How Reanimated works

To better understand the problem, it would be valuable to explain how Reanimated works in React Native.

Reanimated is a library that enables you to create animations in React Native. Its main advantage is speed - by running animations directly on the UI thread and not re-rendering components in the React JavaScript runtime, we can provide a smoother, more responsive experience for users. To achieve that, Reanimated initiates a new JavaScript runtime, which is run on the UI thread. I'll refer to it as a Worklet Runtime. However, animations are usually started from the React JavaScript runtime. Therefore, a way to transfer data from the React Runtime to the Worklet Runtime is needed. This is where useSharedValue comes in.

Why useSharedValue

Everything here applies to useDerivedValue as well.

It's a hook designed to resemble the useRef hook. It doesn't affect the render process of React and it's mainly supposed to be utilized for Worklet Runtime purposes. The hook itself returns an object - which I'll refer to as a Shared Value - that has a getter and a setter on its value property. The actual value of the Shared Value resides in the Worklet Runtime.

The getter does the following:

1. When run on the Worklet Runtime, it synchronously returns the value of the shared value.
2. When run on the React Runtime, it synchronously calls the Worklet Runtime through JSI to obtain the value of the shared value.

The situation is slightly different for the setter:

1. When run on the Worklet Runtime, it synchronously sets the value of the shared value.
2. When run on the React Runtime, it schedules the assignment to be executed on the Worklet Runtime.

None of the setter calls change the reference of the Shared Value.

In general, we discourage the use of Shared Value's getter on the React Runtime. Handling them only on the Worklet Runtime is sufficient in the vast majority of cases. However, some very custom scenarios may still require their use. This should be done as a side effect - depending on Shared Value during render is a bad practice leading to errors - similar to reading from useRef during render.

Why useSharedValue API is valuable in our opinion

Changes to the Shared Value don't trigger a re-render. By having the value property on the Shared Value, we can intuitively show users the resemblance to useRef and lead them to treat it as if it were a mutable object. This is crucial for us since it affords us a more approachable API, which we wouldn't get with an explicit getter and setter. Let's look at a slightly modified example from before:

export default function Component() {
  const width = useSharedValue(100);

  const tap = Gesture.Tap().onFinalize(() => {
    'worklet';
    // Code in here will be executed on the Worklet Runtime.
    width.value += 10;
    if (someCondition) {
      width.value *= 2;
    } else if (otherCondition) {
      width.value /= 2;
    }
  });

  return (
    <View style={styles.container}>
      <GestureDetector gesture={tap}>
        <Animated.View style={[styles.staticBox, { width }]} />
      </GestureDetector>
    </View>
  );
}

The use of an explicit getter and setter would make the Gesture.Tap() callback code look like this:

() => {
  'worklet';
  // Code in here will be executed on the Worklet Runtime.
  setWidth((value) => value + 10);
  if(someCondition){
    setWidth((value) => value * 2);
  } else if (otherCondition) {
    setWidth((value) => value / 2);
  }
};

Which, in our opinion, is harder to read and may adversely impact performance - unfortunately, worklets executed on the Worklet Runtime don't benefit from optimizations (inlining, etc.) that Hermes could provide. Handling the primitives gives us an edge over using lambda functions as arguments.

useSharedValue and Rules of React

Here, I will go over the rules that we believe apply to useSharedValue. Please let me know if I've overlooked something.

Hooks must be pure

useSharedValue honors this rule. On its first call, it creates the Shared Value on the Worklet Runtime (specifically, it prepares the data structure to be constructed on the Worklet Runtime, and the initialization itself is deferred until the first time the value is accessed). The hook always returns the same object with a getter and setter, since it's memoized by useState, and the setter is discarded.

Side effects must run outside of Render

In our view, useSharedValue doesn't produce any side effects.

Don’t mutate State, Return values and arguments to Hooks are immutable & Values are immutable after being passed to JSX

The Shared Value returned by useSharedValue is not mutable. It has getters and setters which only affect values on the Worklet Runtime.

Depending on useSharedValue on render

Using useSharedValue on render is discouraged by the Reanimated team. Since Shared Value's value might be changing on the UI thread, subsequent reads from it on the React Runtime might yield different results. This isn't such a unique case, however. Given video players present in the React ecosystem, getting the current time of the video is a common use case, which yields different results on every call while the video is playing. We believe that developers don't expect this kind of data to trigger a re-render and also acknowledge the possibility that the value is out-of-sync. The same applies to useSharedValue. The same would go for scroll offsets, etc. Looking at these examples:

export default function Component() {
  const scrollableRef = useRef(null);

  const scrollLeft = scrollableRef.current.scrollLeft;

  return (
    <>
      <div className="scrollable" ref={scrollableRef}>
        {/*  */}
        {/* Children */}
        {/*  */}
      </div>
      {/* Doesn't trigger re-renders, `scrollLeft` is out-of-sync */}
      <SomeChild scrollLeft={scrollLeft} />
    </>
  );
}

This would be invalid, as would be the case with Reanimated:

export default function Component() {
  const width = useSharedValue(100);

  const tap = Gesture.Tap().onFinalize(() => {
    'worklet';
    width.value += 10;
  });

  return (
    <View style={styles.container}>
      <GestureDetector gesture={tap}>
        <Animated.View style={[styles.staticBox, { width }]} />
        {/* Doesn't trigger re-renders, `width` is out-of-sync */}
        <Text>{width.value}</Text>
      </GestureDetector>
    </View>
  );
}

The proper solution in React would be to apply scroll handlers that trigger useState - the same case applies in Reanimated, as we provide such APIs.

export default function Component() {
  const width = useSharedValue(100);
  const [widthDisplay, setWidthDisplay] = useState(100);

  const tap = Gesture.Tap().onFinalize(() => {
    'worklet';
    width.value += 10;
  });

  useEffect(() => {
    runOnUI(() => {
      // This listener will update the state on every change of the shared value.
      width.addListener(42, (newValue) => {
        runOnJS(setWidthDisplay)(newValue);
      });
    })();
  }, []);

  return (
    <View style={styles.container}>
      <GestureDetector gesture={tap}>
        <Animated.View style={[styles.staticBox, { width }]} />
        {/* Due to our listener, `widthDisplay` is not out-of-sync */}
        <Text>{widthDisplay}</Text>
      </GestureDetector>
    </View>
  );
}

Hardcoding Reanimated into the Compiler

It's very flattering for us that as a React Native first library we are considered in the Compiler's code. However, I don't believe it's a good long term solution.

useDerivedValue is a hook that utilizes useSharedValue under the hood. Suppose we wanted to add a new hook of this kind. We would need to submit a PR to the Compiler, which would take some time before it's available to users - meanwhile, they would be receiving warnings/errors from the Compiler. Suppose we wanted to change the behavior of some hook - it used to affect the render, and now it doesn't (or vice-versa). This is an even worse scenario, as it could lead users to break their code because they followed outdated definitions in the Compiler.

While these scenarios might seem extreme, we are planning to decouple Reanimated's animations and Reanimated's UI thread utilization, namely worklets, into separate packages. This separation would definitely require contributions to the Compiler, which, again, would reach the users after a delay.

I think that React Native and its libraries are currently much more dynamic than those of React - breaking changes are more frequent and new ways to utilize the native APIs are being introduced all the time. Therefore, a more dynamic approach regarding Reanimated & Compiler integration would be beneficial, in our opinion.

I believe most of the discussion here arises from the fact that Reanimated is the only library handling multiple runtimes over native code, allowing the user to do virtually anything on them. While it might be sufficient for now to hardcode for Reanimated, other multi-threaded libraries of a similar nature are likely to arise in the future.

Could the compiler be configurable?

If we don't want to hardcode things into the Compiler, we could establish some configuration APIs. I understand that the Compiler's aim is to be a plug-n-play solution that shouldn't require any configuration from the user. We don't want to change it. Hence, as an alternative, we could employ the Babel pipeline.

Each Babel plugin can define a pre step for the transpilation process. In this step, we have access to every Babel plugin that is included, and we can modify their options. Back in the day, I made a PoC of this, which looked like this:

pre(state) {
  const plugins = state.opts.plugins;
  const compiler = plugins.find((obj) => {
    return obj.key.includes('react-forget');
  });
  if (compiler) {
    if(!compiler.options.environment){
      compiler.options.environment = {};
    }
    compiler.options.environment.enableCustomTypeDefinitionForReAnimated =
      true;
  }
}

While this only enabled the flag for Reanimated and such manipulation in Compiler's options looks like a hack, we could streamline this process. Since the Compiler is supposed to be listed first, its pre step would be run first, enabling it to expose some functions to facilitate dynamic configurations of this kind.

I understand your points here regarding maintainability and debugging. It is true that third-party plugins could misuse these APIs and break the Compiler. However, as evident from the PoC, that remains a possibility even without them. Naturally, this is just one possible solution and there could be other ways - this approach could be useful for not just Reanimated but potentially other libraries too.

---

Thanks for reading. I wanted to keep it short but you know how it is 🙈. Please keep in mind that this is only our perspective on the matter, and we are open to any feedback. I would be more than happy to answer your questions and listen to your ideas.

[josephsavona]

Hey @tjzel, thanks for the extensive writeup! The compiler team met to discuss this today and i'll share a writeup of our takeaways and suggestions. Our approach was to focus on the core concept that is being modeled, and separate this out from other aspects such as API (getters/setters vs functions) and implementation details. I'll first describe how we think about modeling reanimated and the implications of that model on the API design, and then propose a more pragmatic compromise solution.

Modeling the Use-Case

In this case, there's an external system (the animator) that the product code is manipulating. Updating a shared value mutates that external system, which is a side-effect. Reading the value synchronizes with that external system to get the current value, and that external system may continue to change such that calling read again at a later time returns a different value. That means the read is also a side effect. At a conceptual level, therefore, shared values are really analogous to external mutable stores.

React has a few different APIs for synchronizing with external mutable stores. useSyncExternalStore is designed for reading the value of a store during render, which doesn't apply to Reanimated's use-case. The other option is refs: developers can store the mutable external store and access it via a ref. For example, you can imagine shared.current.set(...), or in setter form shared.current.value = .... Refs themselves are inert mutable state - they are the way to tell React that a value is unsafe for access during render, ie only safe to access in effects/events. Thus the way to model Reanimated's shared values is to put the mutable value inside a ref, and manipulate it through the ref.

Stated another way: refs are a one-off type in React that is not meant to be imitated in other APIs, but rather composed. The long-term "correct" way to do this would be storing the mutable store references inside refs and accessing them through the ref. Whether to use getters/setters or functions (shared.current.get() vs shared.current.value) is just an API design question.

An Alternative

I can imagine that the above is not a very satisfactory answer since it means a breaking API change for y'all. However, understanding the model does help us understand the long-term direction that we should take. Since the right pattern is to use a ref, we don't want to encourage APIs that copy refs rather than compose them. That in turns means we don't need to generalize the compiler to support other instances of this pattern.

Instead, we're hoping we can find a pragmatic solution. Reanimated is unique in our knowledge and we're inclined to try to carve out an exception in this case. We're thinking that we can teach the compiler to ignore "worklet" functions when checking for side effects. This would allow keeping the existing api of shared values, and allow setting .value = inside worklet functions. This would mean we continue to correctly flag writes to shared values during render or from other non-worklet functions. We can enable this mode the same way we're already enabling special behavior for Reanimated. One of the main reasons that this approach can work is that Reanimated heavily discourages accessing .value during render.

I'm curious for your thoughts on this, and whether the idea of allowing mutations inside "worklet" functions could work as a compromise.

[tjzel]

Apologies for my late reply - I was essentially out of office last week and needed appropriate time to answer properly. It's an honor that your team is investing time to discuss Reanimated - we appreciate it.

Relating to the read/write side-effect impacting the external system, I stand corrected, you're right to see it as a side-effect. Our stance aligns with this, since we already discourage users from using getters and setters in render. Thanks for highlighting this.

Reducing the boilerplate

Your idea of wrapping the Shared Value in a Ref is a simple and compelling solution. However, it conflicts with what we perceive the community wants. We frequently receive requests to reduce boilerplate in our APIs, yet this move would increase it. Users might then wrap useSharedValue in their own hook to steer clear of that boilerplate:

function useSharedValue(initial) {
  return Reanimated.useSharedValue(initial).current;
}

In my opinion this is bound to happen since it virtually requires no other changes to the user's code had we shipped this kind of change.

Composition

I hope I didn't misunderstood what you meant by composition here. A while back I noticed that the Compiler does not allow all valid forms of composition. I know myself the limitations of Babel plugins and it's upsetting that we can't get a wider perspective on the code with it. That said, we should not restrict ourselves due to our tools. Here's an example:

function useCustomHook() {
  const ref = useRef<CustomObject>(null!);
  if (ref.current === null) {
    ref.current = initializer();
  }

  useEffect(() => {
    ref.current.doSomethingInternally();
  });

  return ref.current.publicObject;
}

export default function App() {
  const customObject = useCustomHook();

  useEffect(() => {
    customObject.prop += 1; // Error reported by the compiler.
  });

  return (
    <View style={styles.container}>
      <Text>Hello world!</Text>
    </View>
  );
}

Depending on context, this could be valid or invalid.

• It's invalid as it breaks React rules, the object returned by useCustomHook is mutated in App's useEffect.
• It's valid since useCustomHook returns a property of a Ref's current, which is mutable. It's changed (and read) only outside of renders.

If the Compiler had stronger tools this wouldn't be an issue, but unfortunately it's not the case now. The current rules of React are fairly new and changes like these feel slightly radical to me.

Reanimated & the ecosystem

It would be much easier for us to conform to all your proposed changes had Reanimated been a simple, small library. However it's deeply embedded in the React Native ecosystem for a long time; it's utilized by other libraries, it's APIs are a part of other APIs:

• react-native-skia has been integrated with Reanimated for quite a while and it's the foundation of some of its new features, like useVideo.
• react-native-wagmi-charts is another example of a library that facilitates Reanimated under the hood.
  A change in our API of this kind doesn't only result in changes of those libraries internals, but also their APIs. In my opinion this shows how significant of a precedent the requirement of dropping the getter/setter pattern is.

Worklet-only approach

This proposal is compelling but has discrete issues.

• Shared Values aren't mutated only in the Worklet Runtime. Many animations are initiated from React runtime, by using the Shared Value setters.
• Identifying worklets vs non-worklets could be tricky for the Compiler. We are actively researching more methods for automatic workletization, sometimes spanning whole files. This drive comes from user requests advocating for less boilerplate and an API that is less prone to errors if 'worklet' is missed.

For it to work in the current way, I only see the option where Compiler works after Reanimated's Babel plugin had done its job - however this is in direct contradiction with the principle of the Compiler running first. It could obviously ran before and after (maybe it is now already?) but I assume it would require extensive changes to the Compiler - correct me if I'm wrong here.

Give ourselves time

We really would like to work out some compromise here, but the intricacies of Reanimated, React and Compiler are getting in the way here. We are constantly experimenting with new ways of utilizing the tools available to us, trying to bring the worklets to a less invasive, more optimized and less opinionated state. That's why I was thinking if we could spread out over time the restrictions (or rather rule enforcement) that the Compiler brings to the table.

I envision that with some time and now with adequate attention from Reanimates' team we could make that satisfying compromise happen. Disabling the error for Shared Value mutation outside of render by default for the time being would get this issue out of your way and give us room to develop better integration with the Compiler. As a start we can emphasize that we discourage Shared Value .value access in renders, both in the documentation and in the codebase.

[josephsavona]

Thanks for the follow-up.

Your idea of wrapping the Shared Value in a Ref is a simple and compelling solution. However, it conflicts with what we perceive the community wants. We frequently receive requests to reduce boilerplate in our APIs, yet this move would increase it.

I appreciate this. But at the end of the day, the API violates the Rules of React and copies a pattern that was never meant to be copied. Making the API compatible doesn't necessarily have to be more verbose — just because the representation uses a ref, for example, doesn't mean you can't provide get()/set() helper functions that dereference the ref and its inner value. Concretely, shared.value = x could become set(shared, x) which is actually a couple characters shorter. Internally, set() could be something like:

function set(shared, value) {
  assertIsSharedValue(shared.current);
  shared.current.value = value; // or use a lower-level form, and make the .value setter start to warn if called directly
}

You'd have a clear deprecation strategy since the .value setters could start to warn if called directly. An even more forward-looking approach would be to make shared values have a state-like API, ie const [shared, setShared] = useSharedValue() where you call the setter to update.

The point is that there are clear, reasonable options for the API that would allow aligning with React rules and best practices, without sacrificing DX. Yes, they're challenging to roll out given Reanimated's use, but the alternative is locking out all downstream users of Reanimated from using the compiler.

Compromise

A compromise would be to provide the set() style API for users who want to use the compiler, but still keep the current non-ref based implementation. This would allow users to update shared values without the use of a direct property write, and avoid triggering a validation error from the compiler.

Given that this is possible in user-space, and the worklet approach isn't sufficient for the compiler to know when to disable validation, I think this probably the best bet. Other approaches would require even more complexity in the compiler which we can't support. Thoughts on providing a set() API?

[josephsavona]

I also wanted to briefly touch on the "composition" example you gave. This isn't crucial to the overall discussion, but you noted that:

A while back I noticed that the Compiler does not allow all valid forms of composition ... Depending on context, this could be valid or invalid.

Note that the example you gave reads the value of context during render. This is always invalid, and it doesn't matter how you compose it. The correct way to implement this would be to return the ref, not its current value.

[tjzel]

After some thought I really liked your idea of keeping the old API for the users that don't want to opt in the compiler static safety while simultaneously providing a new API compliant with the Compiler. I made a PoC of that and presented it to the team internally. I'll let you know once we conclude the details of the implementation so we could plan ahead.

---

About the composition example - you are absolutely right, I don't know why I haven't registered the read of the .current inside the hook as in render. That made me think about a particular use case where I'm not sure if it's compliant with Rules of React or not:

const useHook(){
  const ref = useRef(null);
  if (ref.current === null) {
    ref.current = something;
  }

  return ref.current; // ref.current will never change
}

Is such code valid provided we ensure ref.current never changes? For me it seems that the return statement mirrors the if condition, since it can be statically evaluated - hence it's valid although sketchy.

[tjzel]

A pull request adding new API is here:

• feat: Add react-compiler safe API to mutables software-mansion/react-native-reanimated#6312