ump-plugin-reanimated

Reanimated Tier 1 surface — SharedValue + useSharedValue + useAnimatedStyle for UMP apps. Sugar over Animated.Value (same C++ ValueRegistry slot, no second JS runtime).

Install

npm install ump-plugin-reanimated

Peer dependencies (must already be installed in your app):

• ump-core
• ump-native

Usage

import { useSharedValue, useAnimatedStyle } from 'ump-plugin-reanimated';
import { Animated } from 'ump-native';

function FadeBox() {
    const opacity = useSharedValue(0);

    const animatedStyle = useAnimatedStyle(() => ({
        opacity: opacity.value,
    }));

    // Drive opacity from any user gesture / timer / animation:
    // opacity.value = 1;

    return <Animated.View style={[{ width: 100, height: 100, backgroundColor: 'tomato' }, animatedStyle]} />;
}

API

| Export | Type | Notes | |-----------------------------------|-------------------------------------------|----------------------------------------------------------------| | SharedValue<T> | class | .value get/set forwards to the underlying AnimatedValue. | | useSharedValue<T>(initial) | hook | Allocates one SharedValue tied to the component's lifetime. | | useAnimatedStyle(factory) | hook | Smart-compiler rewrites callsites; runtime is identity fallback. | | __umpInternalAnimatedStyleBind | runtime helper | Internal — the worklet plugin emits calls to this. Do not invoke directly. |

Types Derivation, AnimatedStyleDescriptor, TransformKey are also exported for advanced/internal use.

How it works

useAnimatedStyle is rewritten at build time by the dev-server's worklet plugin (packages/ump-dev-server/src/worklet-plugin.js) into a call to __umpInternalAnimatedStyleBind with a list of derivations. The helper produces a style object whose values are real AnimatedValue references, picked up by Animated.View's style scanner and bound through the existing C++ animation pipeline.

If the worklet plugin is not installed (e.g. unit tests, non-bundler runs), useAnimatedStyle falls back to invoking the factory once and returning the literal style — functionally correct but with no per-frame animation.

See docs/superpowers/specs/2026-05-22-worklets-strategy.md for the full strategy.

Migration from ump-native

In ump-native 0.1.x, the Reanimated surface was bundled with the main package. Starting 0.2.x, it ships as this separate plugin.

- import { SharedValue, useSharedValue, useAnimatedStyle } from 'ump-native';
+ import { SharedValue, useSharedValue, useAnimatedStyle } from 'ump-plugin-reanimated';

No API changes. The smart-compiler contract (function name + signature) is preserved exactly so the worklet plugin's grep-based rewrite continues to work.