React Native Worklets

https://docs.swmansion.com/react-native-worklets/
Admin
React Native Worklets is a library that allows you to run JavaScript code in parallel on multiple...
Tokens:58,044
Snippets:615
Trust Score:10
Update:3 days ago
Show doc for...
Tokens:
Raw
### Install react-native-worklets package

Source: https://docs.swmansion.com/react-native-worklets/docs/fundamentals/getting-started

Install the library using npm or yarn.

```bash
npm install react-native-worklets
```

```bash
yarn add react-native-worklets
```

--------------------------------

### Install iOS pods

Source: https://docs.swmansion.com/react-native-worklets/docs/fundamentals/getting-started

Install CocoaPods dependencies before running the iOS app.

```bash
cd ios && pod install && cd ..
```

--------------------------------

### globals identifier scoping example

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

Example showing a reference that must be copied to the UI thread to avoid failure.

```javascript
const someReference = 5;  
function foo() {  
  'worklet';  
  return someReference + 1;  
}  
```

--------------------------------

### Configure importForwarding.moduleNames

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

Example of adding a library to the moduleNames list to forward its exports into worklets.

```javascript
/** @type {import('react-native-worklets/plugin').PluginOptions} */  
const workletsPluginOptions = {  
  // ...  
  importForwarding: { moduleNames: ['my-library'] },  
};
```

--------------------------------

### globals identifier null example

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

Example showing an identifier that is already accessible on the UI thread.

```javascript
function bar() {  
  'worklet';  
  return null;  
}  
```

--------------------------------

### Working example with Custom Serializable

Source: https://docs.swmansion.com/react-native-worklets/docs/memory/registerCustomSerializable

Demonstrates how to register a custom serializable to successfully transfer an object with a custom prototype to the UI runtime.

```typescript
const obj = {};  
  
// because why not  
Object.setPrototypeOf(obj, console);  
  
type ConsoleLike = typeof console;  
  
registerCustomSerializable({  
  name: 'ConsoleLike',  
  determine(value: object): value is ConsoleLike {  
    'worklet';  
    return Object.getPrototypeOf(value) === console;  
  },  
  pack(value: ConsoleLike) {  
    'worklet';  
    // We don't need to transfer any data,  
    // so we can pack it to an empty object.  
    return {};  
  },  
  unpack(value: object) {  
    'worklet';  
    // We can recreate the original object.  
    return Object.create(console);  
  },  
});  
  
scheduleOnUI(() => {  
  obj.log('Hello!'); // prints 'Hello!'  
});
```

--------------------------------

### Ambiguous worklet import

Source: https://docs.swmansion.com/react-native-worklets/docs/bundleMode/importForwarding

An example demonstrating the ambiguity of using imports inside a worklet.

```javascript
import { foo } from 'my-library';  
  
function worklet() {  
  'worklet';  
  foo();  
}  
  
scheduleOnUI(worklet);  

```

--------------------------------

### Configure getHBCBinary for Hermes bytecode

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

Example implementation for the experimental hermesBytecode feature, requiring the path to the hermesc binary.

```javascript
/** @type {import('react-native-worklets/plugin').PluginOptions} */  
const workletsPluginOptions = {  
  hermesBytecode: true,  
  getHBCBinary: () => {  
    // Return the absolute path to the `hermesc` binary for the current host machine.  
  },  
};  
```

--------------------------------

### Configure importForwarding.relativePaths

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

Example of adding a library path to the relativePaths list to enable forwarding for relative imports.

```javascript
/** @type {import('react-native-worklets/plugin').PluginOptions} */  
const workletsPluginOptions = {  
  // ...  
  importForwarding: { relativePaths: ['my-library'] },  
};
```

--------------------------------

### Accessing UIRuntimeId

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/uiRuntimeId

Example showing how to import and log the UIRuntimeId constant.

```typescript
import { UIRuntimeId } from 'react-native-worklets';  
  
console.log(UIRuntimeId); // 2  
```

--------------------------------

### globals identifier global object example

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

Example demonstrating how the global object is handled across threads.

```javascript
function setOnJS() {  
  global.something = 'JS THREAD';  
}  
  
function setOnUI() {  
  'worklet';  
  global.something = 'UI THREAD';  
}  
  
function readFromJS() {  
  console.log(global.something);  
}  
  
function readFromUI() {  
  'worklet';  
  console.log(global.something);  
}  
  
function run() {  
  setOnJS();  
  scheduleOnUI(setOnUI);  
  readFromJS();  
  scheduleOnUI(readFromUI);  
}  
```

--------------------------------

### Define relative imports in my-library/index.js

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

Example of a library file using relative imports that are candidates for forwarding.

```javascript
import { someExport } from './utils';  
  
function foo() {  
  'worklet';  
  
  // We want it forwarded.  
  someExport();  
}
```

--------------------------------

### Ambiguous runtime state usage

Source: https://docs.swmansion.com/react-native-worklets/docs/bundleMode/importForwarding

Example showing how imports can be ambiguous when run across different JavaScript runtimes.

```javascript
import { incrementValue, getValue } from 'my-library';  
  
incrementValue();  
  
function worklet() {  
  'worklet';  
  const value = getValue();  
  console.log(value);  
}  
  
scheduleOnUI(worklet); // does it log 0 or 1?  

```

--------------------------------

### Execute a worklet using runOnRuntimeAsyncWithId

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/runOnRuntimeAsyncWithId

Example demonstrating how to create a worklet runtime and execute a computation on it using its runtimeId.

```typescript
import {  
  runOnRuntimeAsyncWithId,  
  createWorkletRuntime,  
} from 'react-native-worklets';  
  
const backgroundRuntime = createWorkletRuntime({ name: 'background' });  
  
async function performHeavyComputation(data: number[]) {  
  const result = await runOnRuntimeAsyncWithId(  
    backgroundRuntime.runtimeId,  
    (numbers: number[]) => {  
      'worklet';  
      return numbers.reduce((sum, n) => sum + n, 0);  
    },  
    data  
  );  
  
  console.log('Computation result:', result);  
}  
```

--------------------------------

### globals identifier output example

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

The output observed when the global object is not blocklisted.

```text
JS THREAD  
JS THREAD  
```

--------------------------------

### Mock implementation for JavaScript

Source: https://docs.swmansion.com/react-native-worklets/docs/guides/testing

Apply this mock in your Jest setup when using JavaScript.

```javascript
jest.mock('react-native-worklets', () =>  
  require('react-native-worklets/lib/module/mock')  
);  
```

--------------------------------

### Configure Metro for Expo

Source: https://docs.swmansion.com/react-native-worklets/docs/bundleMode/setup?worklets-plugin=oxc

Apply the bundle mode configuration to your Metro setup when using Expo.

```javascript
// Learn more https://docs.expo.io/guides/customizing-metro  
const { getDefaultConfig, mergeConfig } = require("expo/metro-config");  
const { getBundleModeMetroConfig } = require("react-native-worklets/bundleMode");  
  
/** @type {import('expo/metro-config').MetroConfig} */  
let config = getDefaultConfig(__dirname);  
  
// Your modifications to the config  
  
config = getBundleModeMetroConfig(config);  
  
module.exports = config;  
```

--------------------------------

### Configure plugin in babel.config.js

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

Example of how to pass the plugin options object to the Worklets Babel plugin within your project's babel.config.js file.

```javascript
/** @type {import('react-native-worklets/plugin').PluginOptions} */  
const workletsPluginOptions = {  
  bundleMode: true,  
  disableInlineStylesWarning: true,  
  globals: ['myObjectOnUI'],  
  substituteWebPlatformChecks: true,  
}  
  
module.exports = {  
  ...  
  plugins: [  
    ...  
    [  
      'react-native-worklets/plugin',  
      workletsPluginOptions  
    ],  
  ],  
};  
```

--------------------------------

### Correct usage of scheduleOnRN

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/scheduleOnRN

This example demonstrates the correct pattern by defining the function in the RN Runtime scope before passing it to scheduleOnRN.

```typescript
import { scheduleOnRN, scheduleOnUI } from 'react-native-worklets';  
  
function App() {  
  //... component code  
  
  // myFunction is defined on the RN Runtime ✅  
  const myFunction = () => {};  
  
  scheduleOnUI(() => {  
    scheduleOnRN(myFunction); // 🥳  
  });  
  
  //... other component code  
}  
```

--------------------------------

### strictGlobal local variable access

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

Example showing how to access a global variable by assigning it to a local variable first.

```javascript
global.something = 10;  
const localSomething = global.something;  
  
function setOnUI() {  
  'worklet';  
  console.log(localSomething); // prints 10  
}  
```

--------------------------------

### Register a Custom Serializable for ConsoleLike objects

Source: https://docs.swmansion.com/react-native-worklets/docs/memory/registerCustomSerializable

Example showing how to register a custom serializable for objects with a console prototype, including the determine, pack, and unpack worklets.

```typescript
const obj = { a: 42 };  
Object.setPrototypeOf(obj, console); // because why not  
  
type ConsoleLike = typeof console;  
  
registerCustomSerializable({  
  name: 'ConsoleLike',  
  determine(value: object): value is ConsoleLike {  
    'worklet';  
    return Object.getPrototypeOf(value) === console;  
  },  
  pack(value: ConsoleLike) {  
    'worklet';  
    return { a: value.a }; // transfer data  
  },  
  unpack(value: object) {  
    'worklet';  
    // recreate object with prototype  
    return Object.create(console, value);  
  },  
});
```

--------------------------------

### Example of worklet scheduling for stack trace debugging

Source: https://docs.swmansion.com/react-native-worklets/docs/guides/feature-flags

This snippet demonstrates how worklets are scheduled on the UI thread. It is used to illustrate how the ENABLE_CROSS_RUNTIME_STACK_TRACES flag affects the visibility of call stacks in LogBox.

```typescript
import { scheduleOnUI } from 'react-native-worklets';  
  
function hardToDebug(callback: () => void) {  
  'worklet';  
  callback();  
}  
  
function functionThatThrows() {  
  'worklet';  
  throw new Error("I'm not!");  
}  
  
function functionThatDoesntThrow() {  
  'worklet';  
  console.log("I'm okay");  
}  
  
export default function App() {  
  // Which invocation throws?  
  scheduleOnUI(hardToDebug, functionThatDoesntThrow);  
  scheduleOnUI(hardToDebug, functionThatThrows);  
  scheduleOnUI(hardToDebug, functionThatDoesntThrow);  
  return null;  
}  
```

--------------------------------

### Failing example without Custom Serializable

Source: https://docs.swmansion.com/react-native-worklets/docs/memory/registerCustomSerializable

Demonstrates that attempting to pass an object with a custom prototype to a worklet without registration will throw an error.

```typescript
const obj = {};  
  
// because why not  
Object.setPrototypeOf(obj, console);  
  
scheduleOnUI(() => {  
  // This will throw because `obj`  
  // had a custom prototype and  
  // it couldn't be serialized.  
  obj.log('Hello!');  
});
```

--------------------------------

### Configure Metro for React Native Community

Source: https://docs.swmansion.com/react-native-worklets/docs/bundleMode/setup?worklets-plugin=oxc

Apply the bundle mode configuration to your Metro setup for standard React Native projects.

```javascript
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 Expo project with prebuild

Source: https://docs.swmansion.com/react-native-worklets/docs/fundamentals/getting-started

Run prebuild to update native code in ios and android directories.

```bash
npx expo prebuild
```

```bash
yarn expo prebuild
```

--------------------------------

### Basic usage of runOnUI

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/runOnUI

Demonstrates how to pass a function to runOnUI and execute it with arguments on the UI thread.

```javascript
import { runOnUI } from 'react-native-worklets';  
  
function App() {  
  // E.g. in event handler or in an effect  
  runOnUI((greeting) => {  
    console.log(`${greeting} from the UI thread`);  
  })('Howdy');  
  
  // ...  
}  
```

--------------------------------

### Interact with Worklet Runtime in C++

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/createWorkletRuntime

Demonstrates how to extract a worklet runtime and execute a worklet using JSI.

```cpp
auto runtime = reanimated::extractWorkletRuntime(rt, runtimeValue);  
  
jsi::Runtime &rt = runtime->getJSIRuntime();  
  
auto worklet = reanimated::extractShareableOrThrow<reanimated::ShareableWorklet>(rt, workletValue);  
  
runtime->runGuarded(worklet, ...args);  
```

--------------------------------

### Create a Shareable

Source: https://docs.swmansion.com/react-native-worklets/docs/memory/shareable

Demonstrates how to initialize a shareable object using createShareable and retrieve its value synchronously.

```javascript
import { createShareable, UIRuntimeId } from 'react-native-worklets';  
  
const shareable = createShareable(UIRuntimeId, 42);  
  
console.log(shareable.getSync()); // 42  
```

--------------------------------

### Basic usage of runOnRuntime

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/runOnRuntime

Demonstrates how to create a worklet runtime and execute a function on it using runOnRuntime.

```typescript
import { createWorkletRuntime, runOnRuntime } from 'react-native-worklets';  
  
const workletRuntime = createWorkletRuntime('background');  
  
function App() {  
  // E.g. in event handler or in an effect  
  runOnRuntime(workletRuntime, (greeting) => {  
    console.log(`${greeting} from a separate thread`);  
  })('Howdy');  
  
  // ...  
}  
```

--------------------------------

### Mock implementation for TypeScript

Source: https://docs.swmansion.com/react-native-worklets/docs/guides/testing

Apply this mock in your Jest setup when using TypeScript.

```javascript
jest.mock('react-native-worklets', () =>  
  require('react-native-worklets/src/mock')  
);  
```

--------------------------------

### Usage of createSynchronizable

Source: https://docs.swmansion.com/react-native-worklets/docs/memory/createSynchronizable

Demonstrates creating a standard Synchronizable and a Synchronizable Fixed with the fixedType configuration.

```javascript
import { createSynchronizable } from 'react-native-worklets';  
  
const synchronizable = createSynchronizable({ a: 42 });  
const counter = createSynchronizable(0, { fixedType: true });  
```

--------------------------------

### Scheduling a worklet on a runtime

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/scheduleOnRuntime

Demonstrates how to create a worklet runtime and schedule a function to run on it using scheduleOnRuntime.

```typescript
import { scheduleOnRuntime, createWorkletRuntime } from 'react-native-worklets';  
  
const workletRuntime = createWorkletRuntime({ name: 'background' });  
  
scheduleOnRuntime(workletRuntime, (greeting: string) => {  
  console.log(`${greeting} from the background Worklet Runtime`);  
}, 'Hello');
```

--------------------------------

### getRuntimeKind example with conditional logging

Source: https://docs.swmansion.com/react-native-worklets/docs/utility/getRuntimeKind

Example showing how to use getRuntimeKind to branch behavior based on runtime. The log function checks if the runtime is ReactNative; otherwise it schedules a log on the RN runtime. The randomDispatch function randomly schedules on UI or calls directly, potentially logging either 'RN: Hello!' or 'UI: Hello!'.

```typescript
import {  
  getRuntimeKind,  
  RuntimeKind,  
  scheduleOnRN,  
  scheduleOnUI,  
} from 'react-native-worklets';  
  
function logToConsole(message: string) {  
  console.log(message);  
}  
  
function log(message: string) {  
  'worklet';  
  if (getRuntimeKind() === RuntimeKind.ReactNative) {  
    console.log(`RN: ${message}`);  
  } else {  
    // Fun fact - this is how `console.log` is implemented on Worklet Runtimes.  
    scheduleOnRN(logToConsole, `UI: ${message}`);  
  }  
}  
  
function randomDispatch() {  
  if (Math.random() > 0.5) {  
    scheduleOnUI(log, 'Hello!');  
  } else {  
    log('Hello!');  
  }  
}  
  
randomDispatch(); // Could log either "RN: Hello!" or "UI: Hello!"  
```

--------------------------------

### isWorkletFunction Declaration Timing

Source: https://docs.swmansion.com/react-native-worklets/docs/utility/isWorkletFunction

Example showing that calling isWorkletFunction before the worklet is declared will return false.

```javascript
isWorkletFunction(myWorklet); // Will always return false.  
  
function myWorklet() {  
  'worklet';  
}  
```

--------------------------------

### Boilerplate in explicit disambiguation

Source: https://docs.swmansion.com/react-native-worklets/docs/bundleMode/importForwarding

Example showing the repetitive boilerplate required when manually disambiguating imports.

```javascript
function incrementOnce() {  
  'worklet';  
  const { getValue, incrementValue } = require('my-library');  
  incrementValue();  
  const value = getValue();  
  console.log(value);  
}  
  
function incrementTwice() {  
  'worklet';  
  const { getValue, incrementValue } = require('my-library');  
  incrementValue();  
  incrementValue();  
  const value = getValue();  
  console.log(value);  
}  
  
// etc...  

```

--------------------------------

### Basic usage of createSerializable

Source: https://docs.swmansion.com/react-native-worklets/docs/memory/createSerializable

Demonstrates how to import and use createSerializable to convert a standard JavaScript object into a serializable reference.

```typescript
import { createSerializable, scheduleOnUI } from 'react-native-worklets';  
  
const object = {  
  a: 1,  
  b: 2,  
  c: 3,  
};  
  
const serializableRef = createSerializable(object);
```

--------------------------------

### Using scheduleOnUI across different runtimes

Source: https://docs.swmansion.com/react-native-worklets/docs/guides/call-tables

Demonstrates calling scheduleOnUI from the RN, UI, and Worker runtimes. Note that calling scheduleOnUI from UI or Worker runtimes requires Bundle Mode to be enabled.

```javascript
import {  
  scheduleOnUI,  
  scheduleOnRuntime,  
  createWorkletRuntime,  
} from 'react-native-worklets';  
  
const workerRuntime = createWorkletRuntime();  
  
// We are on RN Runtime -  
// this is always fine  
scheduleOnUI(/*...*/);  
  
scheduleOnUI(() => {  
  // We are on the UI Runtime -  
  // this is only fine with Bundle Mode enabled  
  scheduleOnUI(/*...*/);  
});  
  
scheduleOnRuntime(workerRuntime, () => {  
  // We are on the Worker Runtime -  
  // this is only fine with Bundle Mode enabled  
  scheduleOnUI(/*...*/);  
});
```

--------------------------------

### strictGlobal disabled behavior

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

Example showing how global variables are captured from the scheduler scope when strictGlobal is disabled.

```javascript
global.something = 10;  
  
function setOnUI() {  
  'worklet';  
  console.log(something); // Captured from scheduler scope, prints 10  
}  
```

--------------------------------

### Asynchronous worklet execution with runOnRuntimeAsync

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/runOnRuntimeAsync

Demonstrates how to create a background runtime and execute a worklet asynchronously to perform heavy computation.

```typescript
import { runOnRuntimeAsync, createWorkletRuntime } from 'react-native-worklets';  
  
const backgroundRuntime = createWorkletRuntime({ name: 'background' });  
  
async function performHeavyComputation(data: number[]) {  
  try {  
    const result = await runOnRuntimeAsync(backgroundRuntime, (numbers: number[]) => {  
      'worklet';  
      // Heavy computation on background thread  
      return numbers.reduce((sum, n) => sum + n, 0);  
    }, data);  
  
    console.log('Computation result:', result);  
  } catch (error) {  
    console.error('Computation failed:', error);  
  }  
}  
```

--------------------------------

### Synchronizable Type Definition

Source: https://docs.swmansion.com/react-native-worklets/docs/memory/synchronizable

Defines the Synchronizable interface with methods for getting and setting values, locking, and unlocking.

```APIDOC
## Synchronizable Type Definition

### Description
Defines the Synchronizable interface with methods for getting and setting values, locking, and unlocking.

### Type Definition
```typescript
type Synchronizable<TValue = unknown> = {
  getDirty(): TValue;
  getBlocking(): TValue;
  setBlocking(value: TValue | ((prev: TValue) => TValue)): void;
  lock(): void;
  unlock(): void;
};
```

### Methods
- **getDirty()** - Returns the current value without blocking.
- **getBlocking()** - Returns the current value, blocking until available.
- **setBlocking(value)** - Sets the value, blocking until the write is complete. Accepts a value or a function that receives the previous value and returns the new value.
- **lock()** - Acquires exclusive access, blocking other threads until unlock is called.
- **unlock()** - Releases exclusive access.
```

--------------------------------

### Create a Worklet Runtime in JavaScript

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/createWorkletRuntime

Initializes a new worklet runtime with a custom name and an initializer function that runs immediately upon creation.

```javascript
import { createWorkletRuntime } from 'react-native-worklets';  
  
function App() {  
  const runtime = createWorkletRuntime({  
    name: 'background',  
    initializer: () => {  
      'worklet';  
      console.log('Runtime initialized!');  
    },  
  });  
}  
```

--------------------------------

### strictGlobal enabled behavior

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

Example showing how global variables are accessed from the worklet global scope when strictGlobal is enabled.

```javascript
global.something = 10;  
  
function setOnUI() {  
  'worklet';  
  console.log(something); // undefined - accessed from worklet global scope  
}  
```

--------------------------------

### Basic usage of runOnJS

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/runOnJS

Demonstrates how to import and use runOnJS to execute a function on the JavaScript thread while currently on the UI thread.

```typescript
import { runOnJS } from 'react-native-worklets';  
  
function App() {  
  // While on the UI thread  
  runOnJS(navigation.goBack)();  
}  
```

--------------------------------

### createShareable(hostRuntimeId, initial, config)

Source: https://docs.swmansion.com/react-native-worklets/docs/memory/createShareable

Creates a Shareable object that can be shared between runtimes. The hostRuntimeId specifies the runtime that will host the Shareable, initial is the initial value, and config provides advanced options like decorators and synchronous initialization.

```APIDOC
## createShareable(hostRuntimeId, initial, config)

### Description
Creates a Shareable object that can be shared between runtimes. The hostRuntimeId specifies the runtime that will host the Shareable, initial is the initial value, and config provides advanced options like decorators and synchronous initialization.

### Parameters

#### hostRuntimeId
- **type**: runtimeId (string or constant)
- **Required**: Yes
- **Description**: The runtimeId of the Worklet Runtime that will host the Shareable. Use the exported constant UIRuntimeId for the UI Runtime, or pass the runtimeId property of a Worker Runtime created with createWorkletRuntime. Hosting on runtimes other than the UI Runtime is available since version 0.9.0.

#### initial
- **type**: Serializable value
- **Required**: Yes
- **Description**: The initial value of the Shareable. It must be a value that is convertible to a Serializable.

#### config
- **type**: object (optional)
- **Required**: No
- **Description**: Optional advanced configuration for the Shareable.

##### config.hostDecorator
- **type**: worklet
- **Required**: No
- **Description**: A worklet that takes the created Shareable Host and decorates it with additional properties or methods. It must return the same reference it received.

##### config.guestDecorator
- **type**: worklet
- **Required**: No
- **Description**: A worklet that decorates each Shareable Guest created for the Shareable with additional properties or methods. It must return the same reference it received.

##### config.initSynchronously
- **type**: boolean
- **Required**: No
- **Description**: By default, the Shareable is initialized asynchronously. Setting this flag to true forces the Shareable to be initialized synchronously during the call to createShareable. It is an escape hatch for situations where your Shareable Host triggers side effects during its initialization.

### Returns
- **type**: Shareable
- **Description**: The created Shareable object.
```

--------------------------------

### Incorrect usage of runOnJS

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/runOnJS

An example of invalid usage where a function is defined within a worklet scope, which will cause an error.

```typescript
withTiming(0, {}, () => {  
  // myFunction is defined on the UI thread 🚨  
  const myFunction = () => {  
    // ...  
  };  
  runOnJS(myFunction)(); // 💥  
});  
```

--------------------------------

### Using createSerializableMap

Source: https://docs.swmansion.com/react-native-worklets/docs/memory/createSerializableTyped

Demonstrates how to initialize a serializable Map and access its values within a worklet using scheduleOnUI.

```typescript
import { createSerializableMap, scheduleOnUI } from 'react-native-worklets';  
  
const serializableMap = createSerializableMap(new Map([['answer', 42]]));  
  
scheduleOnUI(() => {  
  'worklet';  
  console.log(serializableMap.get('answer')); // 42  
});
```

--------------------------------

### Execute function synchronously on RN Runtime

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/runOnRNSync

Example showing how to use runOnRNSync within a worklet to retrieve a value from the RN Runtime.

```typescript
import { runOnRNSync, scheduleOnUI } from 'react-native-worklets';  
  
const getUserName = (): string => store.user.name;  
  
scheduleOnUI(() => {  
  'worklet';  
  const name = runOnRNSync(getUserName);  
  console.log(name);  
});
```

--------------------------------

### Creating Shareable objects on different runtimes

Source: https://docs.swmansion.com/react-native-worklets/docs/memory/createShareable

Demonstrates how to host a Shareable on the UI Runtime using UIRuntimeId and on a custom Worker Runtime using its runtimeId.

```typescript
import {  
  createShareable,  
  createWorkletRuntime,  
  UIRuntimeId,  
} from 'react-native-worklets';  
  
// Shareable hosted on the UI Runtime  
const uiShareable = createShareable(UIRuntimeId, 'hello');  
  
// Shareable hosted on a Worker Runtime  
const workerRuntime = createWorkletRuntime({ name: 'background' });  
const workerShareable = createShareable(workerRuntime.runtimeId, 'hello');
```

--------------------------------

### Using callMicrotasks

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/callMicrotasks

Import and execute the callMicrotasks function to flush the microtask queue from the UI thread.

```javascript
import { callMicrotasks } from 'react-native-worklets';  
  
callMicrotasks();
```

--------------------------------

### Conceptual import forwarding for moduleNames

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

Demonstrates how the plugin conceptually transforms code when a module is included in importForwarding.moduleNames.

```javascript

import { someExport } from 'my-library';  
  
function foo() {  
  'worklet';  
  
  someExport();  
}
```

```javascript
// Preserved in case it's used outside the worklet.  
import { someExport } from 'my-library';  
  
function foo() {  
  'worklet';  
  import { someExport } from 'my-library';  
  someExport(); // Forwarded.  
}
```

--------------------------------

### Incorrect usage of scheduleOnRN

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/scheduleOnRN

This example shows an invalid pattern where a function is defined inside a UI Runtime callback, making it unavailable for scheduleOnRN.

```typescript
import { scheduleOnRN, scheduleOnUI } from 'react-native-worklets';  
  
function App() {  
  //... component code  
  
  scheduleOnUI(() => {  
    // callback is defined on the UI Runtime 🚨  
    scheduleOnRN(() => {}); // 💥  
  });  
  
  //... other component code  
}  
```

--------------------------------

### Shareable Guest Interface

Source: https://docs.swmansion.com/react-native-worklets/docs/memory/shareable

The interface of the Shareable on the Guest Runtimes. It provides methods to asynchronously or synchronously get and set the value on the Host Runtime.

```APIDOC
## Shareable Guest Interface

### Description
The interface of the Shareable on the Guest Runtimes. It provides methods to asynchronously or synchronously get and set the value on the Host Runtime.

### Properties
- **isHost** (boolean) - Indicates whether the Shareable is being accessed from the Host Runtime. Equal to `false`.

### Methods

#### getAsync
- **Description**: An asynchronous method that returns a Promise that resolves to the current value of the Shareable Host.
- **Returns**: Promise<any> - A promise that resolves to the current value.

#### getSync
- **Description**: A synchronous method that preempts the Host Runtime on the current thread, reads the `value` of the Shareable Host, serializes the result, and returns it synchronously.
- **Returns**: any - The current value.

#### setAsync
- **Description**: An asynchronous method that schedules a callback on the Host Runtime to modify the `value` of the Shareable Host.
- **Parameters**:
  - **value** (any | worklet) - Required - The new value or a setter worklet.

#### setSync
- **Description**: A synchronous method that preempts the Host Runtime on the current thread and modifies the `value` of the Shareable Host.
- **Parameters**:
  - **value** (any | worklet) - Required - The new value or a setter worklet.
```

--------------------------------

### getCurrentThreadId usage example

Source: https://docs.swmansion.com/react-native-worklets/docs/utility/getCurrentThreadId

Demonstrates how to retrieve the thread ID from the JS thread, the UI thread via scheduleOnUI, and the UI thread via runOnUISync.

```javascript
import { getCurrentThreadId, runOnUISync, scheduleOnUI } from 'react-native-worklets';  
  
console.log(getCurrentThreadId()); // The JS thread id.  
  
scheduleOnUI(() => {  
  'worklet';  
  console.log(getCurrentThreadId()); // The UI thread id.  
});  
  
runOnUISync(() => {  
    'worklet';  
    console.log(getCurrentThreadId()); // The JS thread id.  
})  
```

--------------------------------

### Create and use Synchronizable with scheduleOnUI

Source: https://docs.swmansion.com/react-native-worklets/docs/memory/synchronizable

Creates a Synchronizable with an initial value and schedules a UI thread callback to read it with getBlocking, while the JS thread sets a new value with setBlocking. The order of execution between the two threads is not guaranteed.

```javascript
import { createSynchronizable, scheduleOnUI } from 'react-native-worklets';  
  
// RN Runtime, JS thread  
  
const synchronizable = createSynchronizable({ a: 42 });  
  
scheduleOnUI(() => {  
  // UI Runtime, UI thread  
  const value = synchronizable.getBlocking();  
  console.log(value); // {a: 24}  
});  
  
// Could execute either before or after the UI Runtime reads the value.  
synchronizable.setBlocking({ a: 24 });  
```

--------------------------------

### Synchronous Remote Function Call Error

Source: https://docs.swmansion.com/react-native-worklets/docs/guides/troubleshooting

Example of a function call that throws an error when executed via scheduleOnUI because the callee is not a worklet or host function.

```javascript
function callee() {  
  console.log('hello');  
}  
function caller() {  
  'worklet';  
  callee(); // <- this will throw in `scheduleOnUI`  
}  
scheduleOnUI(caller);  
```

--------------------------------

### Conceptual import forwarding for relativePaths

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

Demonstrates how the plugin conceptually transforms code when a path is included in importForwarding.relativePaths.

```javascript

import { someExport } from './utils';  
  
function foo() {  
  'worklet';  
  
  someExport();  
}
```

```javascript
// Preserved in case it's used outside the worklet.  
import { someExport } from './utils';  
  
function foo() {  
  'worklet';  
  import { someExport } from './utils';  
  someExport(); // Forwarded.  
}
```

--------------------------------

### Non-granular object access warning

Source: https://docs.swmansion.com/react-native-worklets/docs/guides/troubleshooting

This example shows how accessing an object property in a worklet can trigger a warning when the entire object is copied and made immutable.

```javascript
const obj = { propAccessedInWorklet: 1, propNotAccessedInWorklet: 2 };  
  
function worklet() {  
  'worklet';  
  console.log(obj.propAccessedInWorklet);  
}  
  
scheduleOnUI(worklet);  
obj.propNotAccessedInWorklet = 3; // Warning: Tried to modify key `prop` of an object which has been already passed to a worklet.
```

--------------------------------

### Using isWorkletFunction

Source: https://docs.swmansion.com/react-native-worklets/docs/utility/isWorkletFunction

Demonstrates how to use isWorkletFunction to distinguish between a worklet function and a standard function.

```javascript
import { isWorkletFunction } from 'react-native-worklets';  
  
const workletFunction = () => {  
  'worklet';  
  return 1;  
};  
  
const isWorkletFunction = isWorkletFunction(workletFunction);  
  
console.log(isWorkletFunction); // true  
  
const nonWorkletFunction = () => {  
  return 1;  
};  
  
const isNonWorkletFunction = isWorkletFunction(nonWorkletFunction);  
  
console.log(isNonWorkletFunction); // false  
```

--------------------------------

### Basic usage of scheduleOnRN

Source: https://docs.swmansion.com/react-native-worklets/docs/threading/scheduleOnRN

Demonstrates scheduling a function to run on the RN Runtime while executing on the UI thread.

```typescript
import { scheduleOnRN } from 'react-native-worklets';  
  
function App() {  
  // While on the UI thread  
  scheduleOnRN(navigation.goBack);  
}  
```

--------------------------------

### Incorrect usage of non-shared objects in worklets

Source: https://docs.swmansion.com/react-native-worklets/docs/guides/troubleshooting

This example demonstrates the problematic pattern where a standard object is modified after being passed to a worklet, leading to unexpected results and a warning.

```javascript
const obj = { prop: 1 };  
  
function worklet() {  
  'worklet';  
  console.log(obj.prop);  
}  
  
scheduleOnUI(worklet);  
obj.prop = 2; // Warning: Tried to modify key `prop` of an object which has been already passed to a worklet.  
scheduleOnUI(worklet);
```

--------------------------------

### Define a custom worklet

Source: https://docs.swmansion.com/react-native-worklets/docs/fundamentals/glossary

Shows how to manually create a worklet by adding the 'worklet' directive at the top of a function.

```javascript
function myWorklet() {  
  'worklet';  
  console.log('Running on the UI Runtime (UI thread)');  
}  
```

--------------------------------

### Example of false positive inline styles warning

Source: https://docs.swmansion.com/react-native-worklets/docs/worklets-plugin/plugin-options

This code demonstrates a scenario where the plugin might incorrectly trigger an inline styles warning for a non-shared value property.

```typescript
import { View } from 'react-native';  
  
interface MyProps {  
  taggedWidth: {  
    tag: string;  
    value: number;  
  };  
}  
  
function MyView({ taggedWidth }) {  
  return <View style={{ width: taggedWidth.value }} />; // This triggers a false warning.  
}  
```
Tokens:
Raw