feat(Worklets): docs for new bundle mode (#8759)

## Summary

Requires
- #8744
- #8853

## Test plan

🚀

Author: tjzel

.yarn/patches/react-native-npm-0.83.0.patch

@@ -1,6 +1,6 @@
 {
-  "label": "Experimental",
-  "position": 5,
+  "label": "Bundle Mode",
+  "position": 2,
   "link": {
     "type": "generated-index"
   }

…rklets/docs/experimental/_category_.json …worklets/docs/bundleMode/_category_.jsondocs/docs-worklets/docs/experimental/_category_.json renamed to docs/docs-worklets/docs/bundleMode/_category_.json docs/docs-worklets/docs/experimental/_category_.json renamed to docs/docs-worklets/docs/bundleMode/_category_.json

@@ -0,0 +1,24 @@
+---
+sidebar_position: 1
+sidebar_label: Overview
+slug: /bundleMode
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import ThemedImage from '@theme/ThemedImage';
+
+<ThemedImage
+  sources={{
+    light: useBaseUrl('/img/bundleMode-light.png'),
+    dark: useBaseUrl('/img/bundleMode-dark.png'),
+  }}
+  alt="Bundle Mode conceptual illustration"
+/>
+
+# Overview
+
+Bundle Mode is an experimental feature that gives worklets access to your whole JavaScript bundle - meaning that any code that's present in the bundle can be executed in any worklet and on any runtime. This means that third party libraries can be used in worklets without the need to patch them. It's also a performance improvement as worklets' code can benefit from all the optimizations that pre-compiled bytecode offers.
+
+**We envision the Bundle Mode to be the default way of using worklets in the future.**
+
+Instructions on how to enable it can be found [here](/docs/bundleMode/setup).

docs/docs-worklets/docs/bundleMode/overview.mdx

@@ -0,0 +1,151 @@
+---
+sidebar_position: 2
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import ThemedImage from '@theme/ThemedImage';
+
+# Setup
+
+## Package installation
+
+Install `react-native-worklets` package with the `bundle-mode-preview` tag:
+
+<Tabs groupId="package-managers">
+  <TabItem value="npm" label="NPM">
+    ```bash
+    npm i react-native-worklets@bundle-mode-preview
+    ```
+
+  </TabItem>
+  <TabItem value="yarn" label="YARN">
+    ```bash
+    yarn add react-native-worklets@bundle-mode-preview
+    ```
+
+  </TabItem>
+</Tabs>
+
+## Configure Babel
+
+To use `react-native-worklets`'s Bundle Mode feature, you need to make the following changes in your repository:
+
+1. **Modify your Babel configuration**. [Worklets Babel Plugin](/docs/worklets-babel-plugin/about) needs to know that it has to prepare your code for the Bundle Mode. In your `babel.config.js` file, add the following:
+
+   ```javascript {2-5,13}
+   /** @type {import('react-native-worklets/plugin').PluginOptions} */
+   const workletsPluginOptions = {
+     bundleMode: true,
+     strictGlobal: true, // optional, but recommended
+   }
+
+   module.exports = {
+     presets: [
+       ... // don't add it here :)
+     ],
+     plugins: [
+       ...
+       ['react-native-worklets/plugin', workletsPluginOptions],
+     ],
+   };
+   ```
+
+## Configure Metro
+
+2. **Modify your Metro configuration**. Metro needs to be configured pre-load Bundle Mode entry points into your JavaScript bundle. In your `metro.config.js` file, apply the config required for the bundle mode. For example:
+
+   ```javascript {6-8,16}
+   const {
+     getDefaultConfig,
+     mergeConfig,
+   } = require('@react-native/metro-config');
+
+   const {
+     bundleModeMetroConfig,
+   } = require('react-native-worklets/bundleMode');
+
+   const config = {
+     // Your Metro config
+   };
+
+   module.exports = mergeConfig(
+     getDefaultConfig(__dirname),
+     bundleModeMetroConfig,
+     config
+   );
+   ```
+
+## Configure your app
+
+For Worklets to know that it should run in Bundle Mode, you need to toggle on `WORKLETS_BUNDLE_MODE_ENABLED` static feature flag in your app's `package.json`. You can find instructions on how to enable it [here](/docs/guides/feature-flags).
+
+## Enable seamless Metro bundling
+
+_This step is optional but highly recommended._
+
+If you run the app after just executing the above steps, you will see an error "Failed to get the SHA-1 for ...":
+
+<ThemedImage
+  sources={{
+    light: useBaseUrl('/img/sha-light.png'),
+    dark: useBaseUrl('/img/sha-dark.png'),
+  }}
+  alt="Bundle Mode Metro error logs"
+/>
+
+This is due to fact that Bundle Mode isolates each worklet in a separate module (file) on the fly and the Metro bundler doesn't index these isolated modules in time.
+
+To fix this issue you can do one of the following:
+
+1. Reload the app and Metro a couple of times until Metro picks up all the new modules. You will have to do it each time. Not recommended.
+2. Patch `metro` package for it to synchronously index new modules created by Bundle Mode. This is the recommended approach. **This patch does not require building React Native from source**. You can find patching instructions in the [Worklets repository](https://github.com/software-mansion/react-native-reanimated/tree/main/packages/react-native-worklets/bundleMode/patches).
+
+This patch is a temporary workaround until necessary changes are merged into Metro.
+
+## Enable fast refresh on Worklet Runtimes
+
+_This step is optional but highly recommended._
+
+React Native's Fast Refresh (hot reload) feature doesn't apply to Worklet Runtimes out of the box. Therefore, when you change worklet's code you will see an error "\[Worklets\] Unable to resolve worklet with hash ...".
+
+<ThemedImage
+  sources={{
+    light: useBaseUrl('/img/hot-light.png'),
+    dark: useBaseUrl('/img/hot-dark.png'),
+  }}
+  alt="Bundle Mode Fast Refresh error logs"
+/>
+
+This is due to fact that the Fast Refresh update wasn't sent to the Worklet Runtime and it doesn't know that new worklet with the given hash exists.
+
+To fix this issue you can do one of two thing:
+
+1. Reload the app on each worklet code change. This virtually defeats the purpose of Fast Refresh. Not recommended.
+2. Patch `metro-runtime` package for it to send Fast Refresh updates to Worklet Runtimes. This is the recommended approach. **This patch does not require building React Native from source** You can find patching instructions in the [Worklets repository](https://github.com/software-mansion/react-native-reanimated/tree/main/packages/react-native-worklets/bundleMode/patches).
+
+This patch is a temporary workaround until necessary changes are merged into Metro.
+
+## Final steps
+
+Make sure to clear your Metro bundler's cache to ensure that all the changes are applied correctly.
+
+<Tabs groupId="package-managers">
+  <TabItem value="npm" label="NPM">
+    ```bash
+    npm start -- --reset-cache
+    ```
+  </TabItem>
+  <TabItem value="yarn" label="YARN">
+    ```bash
+    yarn start --reset-cache
+    ```
+  </TabItem>
+</Tabs>
+
+And that's it! You can now happily enjoy the Bundle Mode! You can learn more about using the Bundle Mode [here](/docs/bundleMode/usage).
+
+## Reference
+
+To see how the setup looks in a real project, you can check out the [Bundle Mode Showcase App](https://github.com/software-mansion-labs/Bundle-Mode-showcase-app) repository.

docs/docs-worklets/docs/bundleMode/setup.mdx

@@ -0,0 +1,40 @@
+---
+sidebar_position: 3
+---
+
+# Usage
+
+## Running third party libraries in Worklets
+
+Third party libraries have to be on an allow-list to use them in worklets. This is because libraries can come with side-effects that would break a Worklet Runtime. For instance, a library that imports something from React Native can't be used on a Worklet Runtime. This would load a second instance of React Native and break your app.
+
+To add a library to the allow-list you only need to set the `workletizableModules` option in Worklets Babel plugin, which is an array of library names. For instance, if you want to use `my-library` on a Worklet Runtime.
+
+```javascript
+/** @type {import('react-native-worklets/plugin').PluginOptions} */
+const workletsPluginOptions = {
+  bundleMode: true,
+  strictGlobal: true, // optional, but recommended
+  // highlight-next-line
+  workletizableModules: ['my-library'],
+};
+```
+
+`workletizableModules` API is temporary and will be replaced with a more robust solution in the future.
+
+## Running network requests in Worklets
+
+In React Native ecosystem, new JavaScript runtimes don't come with networking capabilities out of the box. Worklets library provides a simplified version of `fetch` API that can be used on Worklet Runtimes - however, it might not be sufficient for all use cases.
+
+For this reason, to enable `fetch` on Worklet Runtimes you have to toggle the `FETCH_PREVIEW_ENABLED` static feature flag in your app's `package.json`. You can find instructions on how to enable it [here](/docs/guides/feature-flags).
+
+Running `fetch` also requires installing all the patches from the [Bundle Mode setup guide](/docs/bundleMode/setup).
+
+:::note
+We are currently looking for third-party networking solutions that would provide same networking capabilities on Worklet Runtimes as what's available on the RN Runtime. We are open to adopting or integrating with such solutions. If you know about such solutions, please reach out to us on [GitHub](https://github.com/software-mansion/react-native-reanimated/issues).
+
+:::
+
+## Reference
+
+To see how the setup looks in a real project, you can check out the [Bundle Mode Showcase App](https://github.com/software-mansion-labs/Bundle-Mode-showcase-app) repository.

docs/docs-worklets/docs/bundleMode/usage.mdx

@@ -8,9 +8,11 @@ Feature flags allow developers to opt-in for experimental changes or opt-out fro
 
 ## Summary of available feature flags
 
-| Feature flag name                                                 |              Type               | Added in | Removed in | Default value |
-| ----------------------------------------------------------------- | :-----------------------------: | :------: | :--------: | :-----------: |
-| [`IOS_DYNAMIC_FRAMERATE_ENABLED`](#ios_dynamic_framerate_enabled) | [static](#static-feature-flags) |  4.1.0   |  –   |    `true`     |
+| Feature flag name                                                  |              Type               | Added in | Removed in | Default value |
+| ------------------------------------------------------------------ | :-----------------------------: | :------: | :--------: | :-----------: |
+| [`BUNDLE_MODE_ENABLED`](#bundle_mode_enabled-)                     | [static](#static-feature-flags) |  0.8.0   |  –   |    `false`    |
+| [`FETCH_PREVIEW_ENABLED`](#fetch_preview_enabled-)                 | [static](#static-feature-flags) |  0.8.0   |  –   |    `false`    |
+| [`IOS_DYNAMIC_FRAMERATE_ENABLED`](#ios_dynamic_framerate_enabled-) | [static](#static-feature-flags) |  0.6.0   |  –   |    `true`     |
 
 :::info
 
@@ -20,7 +22,16 @@ Feature flags available in `react-native-reanimated` are listed [on this page](h
 
 ## Description of available feature flags
 
-### `IOS_DYNAMIC_FRAMERATE_ENABLED`
+### `BUNDLE_MODE_ENABLED` <AvailableFrom version="0.8.0" />
+
+This feature flag enables [the Bundle Mode](/docs/bundleMode/). Make sure to follow the rest of the [setup instructions](/docs/bundleMode/setup/) after enabling this flag.
+
+### `FETCH_PREVIEW_ENABLED` <AvailableFrom version="0.8.0" />
+
+This feature flag enables the [preview of fetch API on Worklet Runtimes](/docs/bundleMode/usage#running-network-requests-in-worklets) in the [Bundle Mode](/docs/bundleMode/). Make sure to follow the rest of the [setup instructions](/docs/bundleMode/setup/) after enabling this flag.
+**This flag requires `BUNDLE_MODE_ENABLED` flag to be enabled as well.**
+
+### `IOS_DYNAMIC_FRAMERATE_ENABLED` <AvailableFrom version="0.6.0" />
 
 This feature flags is supposed to improve the visual perception and perceived smoothness of computationally expensive animations. When enabled, the frame rate will be automatically adjusted for current workload of the UI thread. For instance, if the device fails to run animations in 120 fps which would usually results in irregular frame drops, the mechanism will fallback to stable 60 fps. For more details, see [PR #7624](https://github.com/software-mansion/react-native-reanimated/pull/7624).
 

docs/docs-worklets/docs/experimental/bundleMode.mdx

@@ -1,6 +1,6 @@
 {
   "label": "Memory",
-  "position": 3,
+  "position": 4,
   "link": {
     "type": "generated-index"
   }

docs/docs-worklets/docs/guides/feature-flags.md

@@ -76,4 +76,4 @@ object.a = 10; // <-- Warning: You can't mutate the object after serializing it
 - This function is rarely used as in almost all cases Worklets handle the creation of Serializables for you.
 - This function includes cycle detection to prevent infinite recursion.
 - `jsi::NativeState` of a passed value is preserved during serialization.
-- Outside of [Bundle Mode](/docs/experimental/bundleMode), `createSerializable` can be called only on the [RN Runtime](/docs/fundamentals/runtimeKinds#rn-runtime). In Bundle Mode, it can be called from any Runtime. If you need to create a Serializable on a [Worklet Runtime](/docs/fundamentals/runtimeKinds#worklet-runtime) outside of Bundle Mode, use deprecated [makeShareableCloneOnUIRecursive](/docs/memory/makeShareableCloneOnUIRecursive) instead.
+- Outside of [Bundle Mode](/docs/bundleMode/), `createSerializable` can be called only on the [RN Runtime](/docs/fundamentals/runtimeKinds#rn-runtime). In Bundle Mode, it can be called from any Runtime. If you need to create a Serializable on a [Worklet Runtime](/docs/fundamentals/runtimeKinds#worklet-runtime) outside of Bundle Mode, use deprecated [makeShareableCloneOnUIRecursive](/docs/memory/makeShareableCloneOnUIRecursive) instead.