chore(Worklets): remove experimental label from Bundle Mode (#9584)

tjzel · web-flow · commit 3206cb1cd934 · 2026-06-17T14:55:41.000Z
## Summary

Let's

## Test plan

go!!!
diff --git a/apps/common-app/src/apps/reanimated/examples/AboutExample.tsx b/apps/common-app/src/apps/reanimated/examples/AboutExample.tsx
@@ -12,7 +12,10 @@ import {
   getStaticFeatureFlag as getStaticFeatureFlagReanimated,
   setDynamicFeatureFlag as setDynamicFeatureFlagReanimated,
 } from 'react-native-reanimated';
-import { getStaticFeatureFlag as getStaticFeatureFlagWorklets } from 'react-native-worklets';
+import {
+  getStaticFeatureFlag as getStaticFeatureFlagWorklets,
+  isBundleModeEnabled,
+} from 'react-native-worklets';
 
 function isWeb() {
   return Platform.OS === 'web';
@@ -61,10 +64,6 @@ function getReactNativeVersion() {
   return `${major}.${minor}.${patch}${prerelease ? `-${prerelease}` : ''}`;
 }
 
-function isBundleModeEnabled() {
-  return !!globalThis._WORKLETS_BUNDLE_MODE_ENABLED;
-}
-
 const staticFlagsReanimated = [
   'DISABLE_COMMIT_PAUSING_MECHANISM',
   'ANDROID_SYNCHRONOUSLY_UPDATE_UI_PROPS',
diff --git a/apps/fabric-example/ios/Podfile.lock b/apps/fabric-example/ios/Podfile.lock
diff --git a/apps/tvos-example/ios/Podfile.lock b/apps/tvos-example/ios/Podfile.lock
diff --git a/docs/docs-worklets/docs/bundleMode/overview.mdx b/docs/docs-worklets/docs/bundleMode/overview.mdx
@@ -17,8 +17,14 @@ dark: useBaseUrl('/img/bundleMode-dark.png'),
 
 # 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.
+Bundle Mode is a 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.**
+**Bundle Mode is considered stable as of version 0.10.0.**
+
+**Bundle Mode will be the default way of using worklets in the future.**
 
 Instructions on how to enable it can be found [here](/docs/bundleMode/setup).
+
+## Legacy Eval Mode
+
+The former way of using worklets - where each worklet is serialized as a string and evaluated individually on the Worklet Runtime - is referred to as **Legacy Eval Mode**. It's still the default mode of running worklets, but we strongly recommend opting out of it with the Bundle Mode.
diff --git a/docs/docs-worklets/docs/guides/call-tables.mdx b/docs/docs-worklets/docs/guides/call-tables.mdx
@@ -9,7 +9,7 @@ Call tables are quick references that show **where a given scheduling function c
 
 ### Why does Bundle Mode matter?
 
-Without Bundle Mode, Worklet Runtimes only have a subset of functionalities of the RN Runtime, due to limitations of serialization of worklets. With Bundle Mode enabled, every runtime has access to the full JavaScript bundle, so most threading APIs become available on all runtimes.
+In [Legacy Eval Mode](/docs/bundleMode#legacy-eval-mode), Worklet Runtimes only have a subset of functionalities of the RN Runtime, due to limitations of serialization of worklets. With Bundle Mode enabled, every runtime has access to the full JavaScript bundle, so most threading APIs become available on all runtimes.
 
 ### How to read a call table
 
diff --git a/docs/docs-worklets/docs/memory/createSerializable.mdx b/docs/docs-worklets/docs/memory/createSerializable.mdx
@@ -75,4 +75,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/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.
+- In [Legacy Eval Mode](/docs/bundleMode#legacy-eval-mode), `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) in Legacy Eval Mode, use deprecated [makeShareableCloneOnUIRecursive](/docs/memory/makeShareableCloneOnUIRecursive) instead.
diff --git a/docs/docs-worklets/docs/memory/createSynchronizable.mdx b/docs/docs-worklets/docs/memory/createSynchronizable.mdx
@@ -35,4 +35,4 @@ The initial value to be held by the created Synchronizable. As it has to be seri
 
 ## Remarks
 
-- Outside of [Bundle Mode](/docs/bundleMode/), `createSynchronizable` can be called only on the [RN Runtime](/docs/fundamentals/runtimeKinds#rn-runtime). In Bundle Mode, it can be called from any Runtime.
+- In [Legacy Eval Mode](/docs/bundleMode#legacy-eval-mode), `createSynchronizable` can be called only on the [RN Runtime](/docs/fundamentals/runtimeKinds#rn-runtime). In Bundle Mode, it can be called on any Runtime.
diff --git a/docs/docs-worklets/src/components/CallTable/index.tsx b/docs/docs-worklets/src/components/CallTable/index.tsx
@@ -27,12 +27,12 @@ function renderCellValue(value: boolean) {
 export function CallTable({ bundleMode, noBundleMode }: CallTableProps) {
   const rows = [
     {
-      label: 'Enabled',
+      label: 'Bundle Mode',
       data: bundleMode,
       className: styles.bundleEnabled,
     },
     {
-      label: 'Disabled',
+      label: 'Legacy Eval Mode',
       data: noBundleMode,
       className: styles.bundleDisabled,
     },
@@ -43,7 +43,7 @@ export function CallTable({ bundleMode, noBundleMode }: CallTableProps) {
       <table className={styles.table}>
         <thead>
           <tr>
-            <th scope="col">Bundle Mode</th>
+            <th scope="col">Mode</th>
             <th scope="col">RN Runtime</th>
             <th scope="col">UI Runtime</th>
             <th scope="col">Worker Runtime</th>
diff --git a/docs/docs-worklets/src/theme/DocSidebar/index.js b/docs/docs-worklets/src/theme/DocSidebar/index.js
@@ -14,11 +14,7 @@ export default function DocSidebarWrapper(props) {
   };
 
   const newItems = [];
-  const experimentalItems = [
-    'bundleMode/overview',
-    'bundleMode/setup',
-    'bundleMode/usage',
-  ];
+  const experimentalItems = [];
   const unreleasedItems = [];
   const deprecatedItems = [
     'threading/callMicrotasks',
diff --git a/docs/docs-worklets/versioned_docs/version-0.10/bundleMode/overview.mdx b/docs/docs-worklets/versioned_docs/version-0.10/bundleMode/overview.mdx
@@ -17,8 +17,12 @@ dark: useBaseUrl('/img/bundleMode-dark.png'),
 
 # 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.
+Bundle Mode is a 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.**
+**Bundle Mode will be the default way of using worklets in the future.**
 
 Instructions on how to enable it can be found [here](/docs/bundleMode/setup).
+
+## Legacy Eval Mode
+
+The former way of using worklets - where each worklet is serialized as a string and evaluated individually on the Worklet Runtime - is referred to as **Legacy Eval Mode**. It's still the default mode of running worklets, but we strongly recommend opting out of it with the Bundle Mode.
diff --git a/docs/docs-worklets/versioned_docs/version-0.10/guides/call-tables.mdx b/docs/docs-worklets/versioned_docs/version-0.10/guides/call-tables.mdx
@@ -9,7 +9,7 @@ Call tables are quick references that show **where a given scheduling function c
 
 ### Why does Bundle Mode matter?
 
-Without Bundle Mode, Worklet Runtimes only have a subset of functionalities of the RN Runtime, due to limitations of serialization of worklets. With Bundle Mode enabled, every runtime has access to the full JavaScript bundle, so most threading APIs become available on all runtimes.
+In [Legacy Eval Mode](/docs/bundleMode#legacy-eval-mode), Worklet Runtimes only have a subset of functionalities of the RN Runtime, due to limitations of serialization of worklets. With Bundle Mode enabled, every runtime has access to the full JavaScript bundle, so most threading APIs become available on all runtimes.
 
 ### How to read a call table
 
diff --git a/docs/docs-worklets/versioned_docs/version-0.10/memory/createSerializable.mdx b/docs/docs-worklets/versioned_docs/version-0.10/memory/createSerializable.mdx
@@ -75,4 +75,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/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.
+- In [Legacy Eval Mode](/docs/bundleMode#legacy-eval-mode), `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) in Legacy Eval Mode, use deprecated [makeShareableCloneOnUIRecursive](/docs/memory/makeShareableCloneOnUIRecursive) instead.
diff --git a/docs/docs-worklets/versioned_docs/version-0.10/memory/createSynchronizable.mdx b/docs/docs-worklets/versioned_docs/version-0.10/memory/createSynchronizable.mdx
@@ -35,4 +35,4 @@ The initial value to be held by the created Synchronizable. As it has to be seri
 
 ## Remarks
 
-- Outside of [Bundle Mode](/docs/bundleMode/), `createSynchronizable` can be called only on the [RN Runtime](/docs/fundamentals/runtimeKinds#rn-runtime). In Bundle Mode, it can be called from any Runtime.
+- In [Legacy Eval Mode](/docs/bundleMode#legacy-eval-mode), `createSynchronizable` can be called only on the [RN Runtime](/docs/fundamentals/runtimeKinds#rn-runtime). In Bundle Mode, it can be called on any Runtime.
diff --git a/docs/docs-worklets/versioned_docs/version-0.10/utility/isBundleModeEnabled.mdx b/docs/docs-worklets/versioned_docs/version-0.10/utility/isBundleModeEnabled.mdx
@@ -0,0 +1,32 @@
+---
+sidebar_position: 42 # Use alphabetical order
+title: isBundleModeEnabled
+---
+
+<Badges version="0.10.0">
+  # isBundleModeEnabled
+</Badges>
+
+Checks whether [Bundle Mode](/docs/bundleMode) is enabled.
+
+For instructions on how to enable Bundle Mode, see the [Bundle Mode documentation](/docs/bundleMode).
+
+## Reference
+
+```typescript
+import { isBundleModeEnabled } from 'react-native-worklets';
+
+console.log(isBundleModeEnabled()); // true if Bundle Mode is enabled
+```
+
+<details>
+  <summary>Type definitions</summary>
+
+  ```typescript
+  function isBundleModeEnabled(): boolean;
+  ```
+</details>
+
+### Returns
+
+`true` if Bundle Mode is enabled, `false` otherwise (including in [Legacy Eval Mode](/docs/bundleMode#legacy-eval-mode) and on the Web).
diff --git a/packages/react-native-worklets/src/debug/bundleMode.native.ts b/packages/react-native-worklets/src/debug/bundleMode.native.ts
@@ -0,0 +1,14 @@
+'use strict';
+
+import type { WorkletFunction } from '../types';
+
+export function isBundleModeEnabled(): boolean {
+  return (
+    globalThis._WORKLETS_BUNDLE_MODE_ENABLED === true &&
+    (
+      (() => {
+        'worklet';
+      }) as WorkletFunction
+    ).__initData === undefined
+  );
+}
diff --git a/packages/react-native-worklets/src/debug/bundleMode.ts b/packages/react-native-worklets/src/debug/bundleMode.ts
@@ -0,0 +1,5 @@
+'use strict';
+
+export function isBundleModeEnabled(): boolean {
+  return false;
+}
diff --git a/packages/react-native-worklets/src/index.ts b/packages/react-native-worklets/src/index.ts
@@ -9,6 +9,7 @@ globalThis._WORKLETS_BUNDLE_MODE_ENABLED = false;
 // is-tree-shakable-suppress
 init();
 
+export { isBundleModeEnabled } from './debug/bundleMode';
 export { toggleSlowAnimationsOnUIRuntime } from './debug/slowAnimations';
 export {
   callMicrotasks,
diff --git a/packages/react-native-worklets/src/specs/index.ts b/packages/react-native-worklets/src/specs/index.ts
@@ -9,5 +9,5 @@ export const WorkletsTurboModule: Spec | null | undefined =
     ? RNWorkletsTurboModule
     : // In Bundle Mode, on Worklet Runtimes `RNWorkletsTurboModule` isn't
       // available and shouldn't be accessed. We return null here
-      // to keep the same codebase for the Bundle Mode and legacy behavior.
+      // to keep the same codebase for the Bundle Mode and Legacy Eval Mode.
       null;
diff --git a/packages/react-native-worklets/src/types.ts b/packages/react-native-worklets/src/types.ts
@@ -68,7 +68,7 @@ interface WorkletInitData {
 interface WorkletProps {
   __closure: WorkletClosure;
   __workletHash: number;
-  /** Only in Legacy Bundling. */
+  /** Only in Legacy Eval Mode. */
   __initData?: WorkletInitData;
   /** Only for Handles. */
   __init?: () => unknown;

Original file line number	Diff line number	Diff line change
`@@ -35,4 +35,4 @@ The initial value to be held by the created Synchronizable. As it has to be seri`
`35`	`35`
`36`	`36`	`## Remarks`
`37`	`37`
`38`		-- Outside of [Bundle Mode](/docs/bundleMode/), `createSynchronizable` can be called only on the [RN Runtime](/docs/fundamentals/runtimeKinds#rn-runtime). In Bundle Mode, it can be called from any Runtime.
	`38`	+- In [Legacy Eval Mode](/docs/bundleMode#legacy-eval-mode), `createSynchronizable` can be called only on the [RN Runtime](/docs/fundamentals/runtimeKinds#rn-runtime). In Bundle Mode, it can be called on any Runtime.