docs: update reanimated docs to be accurate for reanimated v4 (#1313)

Co-authored-by: Jakub Romańczyk <[email protected]>

Author: dannyhw

website/src/latest/docs/features/reanimated.mdx

@@ -2,69 +2,93 @@ import { PackageManagerTabs } from '@theme';
 
 # React Native Reanimated
 
-Re.Pack provides first-class support for [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/) through a dedicated plugin that simplifies integration and optimizes build performance.
+Re.Pack provides first-class support for [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated/) through a dedicated plugin that simplifies integration and in some cases, optimizes your build performance.
 
-:::warning This plugin is primarily intended for Rspack users.
+:::info This plugin is primarily used to disable console warnings that are not relevant when bundling a React Native app.
 
-The main purpose of this plugin is to limit the **build performance impact** of the `react-native-reanimated` babel plugin.
+:::
 
-If you're using webpack with `babel-loader`, you probably don't need this plugin. Instead, you should follow the [official Reanimated documentation](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/#step-2-add-reanimateds-babel-plugin) and add the Reanimated Babel plugin directly to your `babel.config.js`:
+## How it Works
 
-```js
-module.exports = {
-  presets: ["module:@react-native/babel-preset"],
-  plugins: ["react-native-reanimated/plugin"],
-};
-```
+The Worklets Babel Plugin transforms your code so that it can run on the Worklet Runtimes. It looks for functions marked with a `'worklet';` directive and converts them into serializable objects.
 
-:::
+When using Rspack, the worklets babel plugin is executed via `babel-swc-loader`. The `ReanimatedPlugin` handles configuration and suppresses warnings that would otherwise appear during the build process.
 
-## How It Works
+## Installation
 
-### The Problem
+If you haven't already, install the `react-native-reanimated` package:
 
-React Native Reanimated requires a special Babel plugin to transform your code, particularly functions marked with `'worklet'`. 
-This transformation is necessary but comes with a cost - the babel transformation can slow down your build process significantly 
-when applied to all files. With Rspack under the hood, we want to make sure that we use `babel-loader` only as a last resort.
+<PackageManagerTabs command="install react-native-reanimated" />
 
-### The Solution
+To add Reanimated support to your Re.Pack project with Rspack, install the plugin:
 
-Our plugin takes a smarter approach by only applying the Reanimated transformation to files that actually need it:
+<PackageManagerTabs command="install -D @callstack/repack-plugin-reanimated" />
 
-- **Smart Detection**: Before running babel, we scan files for Reanimated keywords like `worklet`
-- **Targeted Processing**: Only files containing these keywords go through the transformation
-- **Performance Boost**: Everything else skips this heavy processing step
+## Usage with Reanimated 4+
 
-In simple terms: we make your builds faster by only doing the heavy Reanimated processing where it's actually needed.
+For Reanimated 4 and above, the worklet transformation is handled by the `react-native-worklets/plugin` babel plugin.
 
-:::note Credits
-Shoutout to [Nate Wienert](https://x.com/natebirdman) who came up with a similar approach in [one.dev](https://one.dev) - his work was the inspiration for this plugin.
-:::
+Install the worklets package:
 
-## Installation
+<PackageManagerTabs command="install react-native-worklets" />
 
-If you haven't already, install the `react-native-reanimated` package:
+### Babel Configuration
 
-<PackageManagerTabs command="install react-native-reanimated" />
+Add the worklets plugin to your `babel.config.js`:
 
-To add Reanimated support to your Re.Pack project with Rspack, install the plugin:
+```js title="babel.config.js"
+module.exports = {
+  presets: ["module:@react-native/babel-preset"],
+  plugins: ["react-native-worklets/plugin"],
+};
+```
 
-<PackageManagerTabs command="install -D @callstack/repack-plugin-reanimated" />
+### Rspack Configuration
+
+Add the plugin to your Rspack configuration with the `unstable_disableTransform` option set to `true`.
+
+```js title="rspack.config.cjs"
+const Repack = require("@callstack/repack");
+const { ReanimatedPlugin } = require("@callstack/repack-plugin-reanimated");
 
-## Usage
+module.exports = {
+  plugins: [
+    new Repack.RepackPlugin(),
+    new ReanimatedPlugin({
+      unstable_disableTransform: true,
+    }),
+  ],
+};
+```
 
-### Plugin Configuration
+This will disable adding now redundant `babel-loader` rules, and defer the transformation to Babel through `babel-swc-loader`.
+
+
+## Usage with Reanimated 3
+
+First add the `react-native-reanimated` babel plugin to your `babel.config.js`:
+
+```js title="babel.config.js"
+module.exports = {
+  presets: ["module:@react-native/babel-preset"],
+  plugins: [
+    "react-native-reanimated/plugin",
+  ],
+};
+```
 
-Add the plugin to your Rspack configuration file (`rspack.config.js`):
+Then apply the `ReanimatedPlugin` with the  unstable_disableTransform option set to `true`.
 
 ```js title="rspack.config.cjs"
 const Repack = require("@callstack/repack");
 const { ReanimatedPlugin } = require("@callstack/repack-plugin-reanimated");
 
 module.exports = {
   plugins: [
-      new Repack.RepackPlugin(),
-      new ReanimatedPlugin(),
-    ],
+    new Repack.RepackPlugin(),
+    new ReanimatedPlugin({
+      unstable_disableTransform: true,
+    }),
+  ],
 };
 ```