createSerializable

Recursively converts JavaScript values into Serializable references that can be passed to different JavaScript Runtimes.

The returned reference cannot be manipulated as it doesn't represent any standard JavaScript object. Changes to the original value don't affect the Serializable.

Functions like scheduleOnUI, runOnUISync, scheduleOnRuntime etc. automatically convert values to Serializable references.

See the passing a copy simulation to follow an object from RN to UI and see why changing the received copy leaves the original unchanged.

Reference

Code

Code

Colours connect each executing thread to its current code line. Recently executed lines fade over the next three ticks.

1(globalThis.settings = { volume: 10 });

2const settingsRef = createSerializable(globalThis.settings);

3

4function logOriginal() {

5 console.log('RN original:', globalThis.settings.volume); // 10

6}

7

8function changeCopy(settings) {

9 'worklet';

10 (globalThis.settings = settings);

11 (globalThis.settings.volume = 20);

12 console.log('UI copy:', globalThis.settings.volume); // 20

13 scheduleOnRN(logOriginal);

14}

15

16// The Serializable is deserialized into a JavaScript object on UI.

17scheduleOnUI(changeCopy, settingsRef);

The createSerializable call creates the immutable value shown in Shared native memory. The reference is then passed to UI, where it is deserialized into a separate JavaScript object. Changing UI's copy leaves both the Serializable and RN's original unchanged.

Type definitions

function createSerializable<TValue>(value: TValue): SerializableRef<TValue>;

Arguments

value

The JavaScript value to be converted into a Serializable reference. It must be one of the supported types listed below.

Type	Supported
string	yes
number	yes
boolean	yes
object	yes
array	yes
function (non-worklet)	yes
HostObject	yes
worklet	yes
Map	yes
Set	yes
ArrayBuffer	yes
RegExp	yes
Cyclic objects	no
Objects with custom prototype	no

note

In development builds, the value argument is frozen after serialization. This prevents misconceptions that changes to the original value would update the already created Serializable.

import { createSerializable, scheduleOnUI } from 'react-native-worklets';

const object = {
  a: 1,
  b: 2,
  c: 4,
};

object.c = 3; // <-- Correct: you can modify the object before serializing it

scheduleOnUI(() => {
  // `object` was implicitly serialized with `createSerializable` when passed to `scheduleOnUI`.
  console.log(object); // { a: 1, b: 2, c: 3 }
});

object.a = 10; // <-- Warning: You can't mutate the object after serializing it

Returns

SerializableRef - a reference to the Serializable representation of the input value.

Remarks

• This function automatically detects the type of the input value and applies appropriate serialization strategies.
• For objects and arrays, it recursively processes nested properties.
• This function is rarely used as in almost all cases the Worklets library handles 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.
• In Legacy Eval Mode, createSerializable can be called only on the RN Runtime. In Bundle Mode, it can be called from any Runtime. If you need to create a Serializable on a Worklet Runtime in Legacy Eval Mode, use deprecated makeShareableCloneOnUIRecursive instead.