docs: update Reanimated 4 docs (#6931)

kacperkapusciak · MatiPl01 · web-flow · commit 4e477780ea19 · 2025-01-24T14:09:58.000Z
This PR updates Reanimated 4 documentation:

- updates installation steps in Getting Started
- removes `paper-example` mentions from Contributing
- documents `textShadow` style props behavior

---------

Co-authored-by: Mateusz Łopaciński &lt;lop.mateusz.2001@gmail.com&gt;
diff --git a/packages/docs-reanimated/docs/fundamentals/getting-started.mdx b/packages/docs-reanimated/docs/fundamentals/getting-started.mdx
@@ -20,54 +20,51 @@ With Reanimated, you can easily create smooth animations and interactions that r
 Reanimated 4.x works only with [the React Native New Architecture (Fabric)](https://reactnative.dev/architecture/landing-page).
 If your app still uses the old architecture, you can use Reanimated in version 3 which is still actively maintained.
 
-## Quick start
+Alternatively, you can dive into [our examples](https://github.com/software-mansion/react-native-reanimated/tree/3.14.0/apps/common-app/src/examples) on GitHub.
+
+## Installation
+
+It takes two steps to add Reanimated 4 to an Expo project:
+
+### Step 1: Install the package
 
-If you don't have an existing project, you can create a new Expo app using a template:
+Install `react-native-reanimated@next` package from npm:
 
 <Tabs groupId="package-managers">
   <TabItem value="npm" label="NPM">
 
-    npx create-expo-app@latest my-app -e with-reanimated
+    npm install react-native-reanimated@next
 
   </TabItem>
   <TabItem value="yarn" label="YARN">
 
-    yarn create expo-app my-app -e with-reanimated
+    yarn add react-native-reanimated@next
 
   </TabItem>
 </Tabs>
 
-Alternatively, you can dive into [our examples](https://github.com/software-mansion/react-native-reanimated/tree/3.14.0/apps/common-app/src/examples) on GitHub.
-
-## Installation
+### Step 2: Rebuild native dependencies
 
-It takes three steps to add Reanimated to a project:
-
-### Step 1: Install the package
-
-Install `react-native-reanimated` package from npm:
+Run prebuild to update the native code in the `ios` and `android` directories.
 
 <Tabs groupId="package-managers">
-  <TabItem value="expo" label="EXPO" default>
-
-    npx expo install react-native-reanimated
-
-  </TabItem>
   <TabItem value="npm" label="NPM">
 
-    npm install react-native-reanimated
+    npx expo prebuild
 
   </TabItem>
   <TabItem value="yarn" label="YARN">
 
-    yarn add react-native-reanimated
+    yarn expo prebuild
 
   </TabItem>
 </Tabs>
 
-### Step 2: Add Reanimated's babel plugin
+And that's it! Reanimated 4 is now configured in your Expo project.
+
+### React Native Community CLI
 
-Add `react-native-reanimated/plugin` plugin to your `babel.config.js`.
+When using [React Native Community CLI](https://github.com/react-native-community/cli), you also need to manually add the `react-native-reanimated/plugin` plugin to your `babel.config.js`.
 
 ```js {7}
   module.exports = {
@@ -92,44 +89,15 @@ Add `react-native-reanimated/plugin` plugin to your `babel.config.js`.
 
 In short, the Reanimated babel plugin automatically converts special JavaScript functions (called [worklets](/docs/fundamentals/glossary#worklet)) to allow them to be passed and run on the UI thread.
 
-To learn more about the plugin head onto to [Reanimated babel plugin](/docs/fundamentals/glossary#reanimated-babel-plugin) section.
-
-</details>
-
-### Step 3: Wrap metro config with reanimated wrapper (recommended)
-
-Wrap your existing Metro configuration in the `metro.config.js` file with the `wrapWithReanimatedMetroConfig` function.
+Since [Expo SDK 50](https://expo.dev/changelog/2024/01-18-sdk-50), the Expo starter template includes the Reanimated babel plugin by default.
 
-```js
-// metro.config.js
-const {
-  wrapWithReanimatedMetroConfig,
-} = require('react-native-reanimated/metro-config');
-
-const config = {
-  // Your existing Metro configuration options
-};
-
-module.exports = wrapWithReanimatedMetroConfig(config);
-```
-
-<details>
-<summary>Why should I do this?</summary>
-
-Wrapping your Metro configuration with the Reanimated Metro config wrapper will result in displaying improved reanimated errors and warnings with more accurate call stacks. Thanks to this, identifying misuses of the Reanimated API will be much easier than before.
-
-To learn more about this feature, head onto to [Accurate Call Stacks](/docs/debugging/accurate-call-stacks).
+To learn more about the plugin head onto to [Reanimated babel plugin](/docs/fundamentals/glossary#reanimated-babel-plugin) section.
 
 </details>
 
-### Step 4: Clear Metro bundler cache (recommended)
+#### Clear Metro bundler cache (recommended)
 
 <Tabs groupId="package-managers">
-  <TabItem value="expo" label="EXPO" default>
-
-    npx expo start -c
-
-  </TabItem>
   <TabItem value="npm" label="NPM">
 
     npm start -- --reset-cache
@@ -142,16 +110,6 @@ To learn more about this feature, head onto to [Accurate Call Stacks](/docs/debu
   </TabItem>
 </Tabs>
 
-### Expo development build
-
-When using an [Expo development build](https://docs.expo.dev/develop/development-builds/introduction/), run prebuild to update the native code in the `ios` and `android` directories.
-
-```bash
-npx expo prebuild
-```
-
-### Platform specific setup
-
 #### Android
 
 No additional steps are necessary.
@@ -171,11 +129,6 @@ For building apps that target web using [react-native-web](https://www.npmjs.com
 To use Reanimated on the web all you need to do is to install and add [`@babel/plugin-proposal-export-namespace-from`](https://babeljs.io/docs/en/babel-plugin-proposal-export-namespace-from) Babel plugin to your `babel.config.js`.
 
 <Tabs groupId="package-managers">
-  <TabItem value="expo" label="EXPO" default>
-
-    npx expo install @babel/plugin-proposal-export-namespace-from
-
-  </TabItem>
   <TabItem value="npm" label="NPM">
 
     npm install @babel/plugin-proposal-export-namespace-from
diff --git a/packages/docs-reanimated/docs/guides/contributing.mdx b/packages/docs-reanimated/docs/guides/contributing.mdx
@@ -25,7 +25,6 @@ The React Native Reanimated repository is a monorepo with the following structur
 ```
 ├── apps
 │   ├── common-app // shared source code of example apps
-│   ├── paper-example // React Native app wrapper running the Old Architecture for shared examples
 │   ├── fabric-example // React Native app wrapper running the New Architecture for shared examples
 │   ├── macos-example // React Native for MacOS app wrapper for shared example code
 │   ├── next-example // Next.js wrapper for shared example code
@@ -34,6 +33,7 @@ The React Native Reanimated repository is a monorepo with the following structur
 └── packages
     ├── docs-reanimated // documentation described further in Helping with documentation
     ├── eslint-plugin-reanimated // source of eslint plugin
+    ├── react-native-worklets // source of worklets package
     └── react-native-reanimated
         ├── android // source code of Android native implementation
         ├── apple // source code of iOS native implementation
@@ -215,7 +215,19 @@ We have shared code of example app, that is run on different platforms and archi
 - `packages/react-native-reanimated/android/src/main/java/com/swmansion/reanimated` &ndash; containing source code related to Android native part of Reanimated features
 - `packages/react-native-reanimated/apple` &ndash; containing source code related to iOS native part of Reanimated features
 
-Our workflow usually starts from editing `apps/common-app/src/examples/EmptyExample.tsx` with testing example for our new feature or a bug. This is the part that we often attach to PR so other developers can test the same use-case (remember not to commit your changes from `EmptyExample` file!). Next, we run the `apps/paper-example` (or `apps/fabric-example` depending on the architecture) app and start development.
+We use two separate example apps depending on the feature or a bug we're currently working on. If the code relates to CSS Animations then we start from editing
+
+```
+apps/common-app/src/apps/css/examples/animations/screens/testExamples/Playground.tsx
+```
+
+For other features like worklet API, Layout Animations and Shared Element Transitions we would usually start from editing
+
+```
+apps/common-app/src/apps/reanimated/examples/EmptyExample.tsx
+```
+
+This is the part that we often attach to PR so other developers can test the same use-case (remember not to commit your changes from `Playground`/`EmptyExample` file!). Next, we run the `apps/fabric-example` app and start development.
 
 :::info
 
@@ -228,10 +240,10 @@ If you want to implement a new feature or fix a bug, but still are unsure after
 To start with, let's install all dependencies:
 
 1. `yarn && yarn build`
-2. `cd apps/paper-example`
+2. `cd apps/fabric-example`
 3. `yarn start` &ndash; make sure to start metro bundler before building the app in Android Studio.
 
-and open `react-native-reanimated/apps/paper-example/android` with Android Studio.
+and open `react-native-reanimated/apps/fabric-example/android` with Android Studio.
 
 <img src={useBaseUrl('/img/contributing/android_studio.png')} />
 
@@ -242,10 +254,10 @@ The native source code of Reanimated can be found in `react-native-reanimated` m
 To begin with, let's install all the necessary dependencies:
 
 1. `yarn && yarn build`
-2. `(cd apps/paper-example/ios && bundle install && bundle exec pod install)` &ndash; install Pods for iOS
-3. `cd apps/paper-example && yarn start` &ndash; make sure to start metro bundler before building the app in Xcode.
+2. `(cd apps/fabric-example/ios && bundle install && bundle exec pod install)` &ndash; install Pods for iOS
+3. `cd apps/fabric-example && yarn start` &ndash; make sure to start metro bundler before building the app in Xcode.
 
-and open `react-native-reanimated/apps/paper-example/ios/ReanimatedExample.xcworkspace` with Xcode.
+and open `react-native-reanimated/apps/fabric-example/ios/ReanimatedExample.xcworkspace` with Xcode.
 
 <img src={useBaseUrl('/img/contributing/xcode.png')} />
 
diff --git a/packages/docs-reanimated/docs/guides/supported-properties.mdx b/packages/docs-reanimated/docs/guides/supported-properties.mdx
@@ -182,3 +182,72 @@ Yoga calculates borders in different ways for numeric values and relative (%) va
 ### flexBasis
 
 Even though changes of this property are calculated properly during the animation, they aren't applied to the view. Other flex properties, such as `flexGrow` and `flexShrink` work fine, so they could be used for animations.
+
+### Animating text shadow styles
+
+On the web, all text shadow styles (i.e. `textShadowColor`, `textShadowOffset`, `textShadowRadius`) need to be specified in the animation keyframes to preserve the style during animation.
+
+iOS and Android text shadow styles doesn't have this limitations and work as intended.
+
+So, for example, if we want to have a shadow color and animate the shadow radius, we can't specify `textShadowColor` just in the element style but we also have to add it to every keyframe of the animation, even though only the `textShadowRadius` is the style we want to animate. Consider this:
+
+```jsx
+<Animated.Text
+  style={{
+    animationName: {
+      from: {
+        textShadowRadius: 8, // while the shadow radius correctly animates from 8 ✅
+      },
+      to: {
+        textShadowRadius: 16, // to 16 ✅
+      },
+    },
+    textShadowColor: 'red', // 🚨 the shadow color would be overridden in the animation keyframes
+    // that means the shadow would be black!
+  }}>
+  Reanimated
+</Animated.Text>
+```
+
+To mitigate this limitation, you need to specify the `textShadowColor` in every keyframe definition:
+
+```jsx
+<Animated.Text
+  style={{
+    animationName: {
+      from: {
+        textShadowColor: 'red', // shadows starts 'red'
+        textShadowRadius: 8,
+      },
+      to: {
+        textShadowColor: 'red', // and keeps being 'red' throughout the animation
+        textShadowRadius: 16,
+      },
+    },
+  }}>
+  Reanimated
+</Animated.Text>
+```
+
+<details>
+<summary>Why do I need this?</summary>
+
+In CSS the `text-shadow` is a single property but in React Native that's three separate properties for color, offset and radius. Because of that Reanimated has to provide these default values to every keyframe definition:
+
+```json
+{
+  "textShadowColor": "#000",
+  "textShadowRadius": 0,
+  "textShadowOffset": { "width": 0, "height": 0 }
+}
+```
+
+and the shadow styles aren't inherited from the style object provided to the element. To retain the styles in an animation you need to override these styles to achieve your expected result.
+
+</details>
+
+### Animating box shadow styles
+
+Similarly to the text shadow styles - all shadow styles (i.e. `shadowColor`, `shadowOffset`, `shadowOpacity`, `shadowRadius`) need to be specified in the animation keyframes to preserve the style during animation on the Web. Keep in mind that `shadowOffset`, `shadowOpacity`, `shadowRadius` style properties [aren't implemented on Android in React Native](https://reactnative.dev/docs/shadow-props#props) so they also can't be animated.
+
+We highly recommend to use [the `boxShadow` property](https://reactnative.dev/blog/2024/10/23/release-0.76-new-architecture#boxshadow) which doesn't have this limitation and also works on Android.
