Bundle Mode

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 3rd party libraries can be used in worklets without any tricks like patching them with a 'worklet' directive.

Setup

Bundle Mode is available from react-native-worklets 0.4, but for best experience and up-to-date features we recommend using the latest version of react-native-worklets from the bundle-mode-preview tag.

yarn add react-native-worklets@bundle-mode-preview

or

npm i react-native-worklets@bundle-mode-preview

All platforms

To use react-native-worklets's Bundle Mode feature, you need to make the following changes in your repository:

1. Modify your Babel configuration. In your babel.config.js file, add the following:

   module.exports = {
     plugins: [
       [
         'react-native-worklets/plugin',
         {
           bundleMode: true,
         },
       ],
       // Your other plugins...
     ],
   };

   Example reference.

2. Modify your Metro configuration. In your metro.config.js file, apply the config required for the bundle mode. For example:

   const {
     getDefaultConfig,
     mergeConfig,
   } = require('@react-native/metro-config');
   const {
     bundleModeMetroConfig,
   } = require('react-native-worklets/bundleMode');
   
   const config = {
     // Your config
   };
   
   module.exports = mergeConfig(
     getDefaultConfig(__dirname),
     bundleModeMetroConfig,
     config
   );

   Example reference

3. Apply the necessary package patches from worklets repository.

iOS

1. Modify your Podfile. In your ios/Podfile, add the following:

# top level
ENV['WORKLETS_BUNDLE_MODE'] = '1'

Example reference

2. Make sure to reinstall your pods.

Android

1. Enable building React Native from source.

   Example reference

2. Modify your gradle.properties. In your android/gradle.properties, add the following:

   workletsBundleMode=true

   Example reference

Usage

Currently, third party libraries have to be on an allow-list to use them in worklets. This is because some libraries come with side-effects that would break a Worklet Runtime. For instance, a library that imports something from React Native cannot be used in Worklets, because loading a second instance of React Native on another runtime would break your app.

To add a library to the allow-list you only need to change 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:

module.exports = {
  plugins: [
    [
      'react-native-worklets/plugin',
      {
        bundleMode: true,
        workletizableModules: ['my-library'],
      },
    ],
    // Your other plugins...
  ],
};

Example reference.