react-native-worklets
@amazon-devices/react-native-workletsは、Reanimatedのパフォーマンス機能の基盤を提供するReact Nativeのマルチスレッドライブラリです。これにより、JavaScriptコードを複数のスレッドやランタイムで並行して実行することが可能になり、メインのJavaScriptスレッドをブロックしないスムーズなアニメーションと対話操作を実現できます。
ワークレットとは
ワークレットとは、シリアル化して異なるスレッドで実行できるJavaScript関数です。関数を'worklet'ディレクティブでマークすると、その関数はBabelプラグインによってシリアル化可能な形式に変換され、UIスレッドやほかのカスタムランタイムにコピーして実行できるようになります。
主な機能
- マルチスレッド: JavaScriptコードを別のスレッド(UIスレッド、カスタムワークレットランタイム)で実行します。
- ゼロコピーシリアル化: パフォーマンスのオーバーヘッドなしに、スレッド間で関数を効率的に転送します。
- Babelプラグインの統合: マークされた関数を自動的にワークレットに変換します。
- ランタイムの作成: 特定用途のワークロード用にカスタムJavaScriptランタイムを作成します。
- シームレスな統合: アニメーションとジェスチャーのためにReanimatedと透過的に連携します。
ドキュメント
このライブラリの情報、APIリファレンス、その他の詳細については、専用のドキュメントページ(https://docs.swmansion.com/react-native-worklets/)(英語のみ)を参照してください。
インストール
-
package.jsonファイルにJavaScriptライブラリの依存関係を追加します。"dependencies": { ... "@amazon-devices/react-native-worklets": "~1.0.0" } babel.config.jsに@amazon-devices/react-native-worklets/pluginプラグインを追加します。module.exports = { presets: [ ... // ここには追加しないでください ], plugins: [ ... '@amazon-devices/react-native-worklets/plugin', ], };npm start -- --reset-cacheコマンドを使用して、Metroバンドラーのキャッシュを消去します。npm installコマンドを使用して、package-lock.jsonファイルを再インストールします。- さらに詳しい情報が必要な場合は、外部ドキュメントのinstallationセクション(英語のみ)を参照してください。
例
並列処理のためにカスタムワークレットランタイムを作成して使用するデモ
import React, { useState } from 'react';
import { Button, StyleSheet, View, Text } from 'react-native';
import { createWorkletRuntime, runOnRuntime, runOnJS } from '@amazon-devices/react-native-worklets';
/**
* カスタムワークレットランタイムの例
* 並列処理のためにカスタムワークレットランタイムを作成して使用するデモを示します。
*/
export default function WorkletCustomRuntimeExample() {
const [result, setResult] = useState<string>('');
const handlePress = () => {
setResult('処理中...');
// イニシャライザーを指定してカスタムランタイムを作成します。
const customRuntime = createWorkletRuntime('myCustomRuntime', () => {
'worklet';
console.log('カスタムランタイムが初期化されました');
});
// カスタムランタイムでコードを実行します。
runOnRuntime(customRuntime, () => {
'worklet';
console.log('カスタムランタイムで実行しています');
// UIスレッドやJSスレッドをブロックすることなく負荷の高い計算を実行します。
let sum = 0;
for (let i = 0; i < 1000000; i++) {
sum += i;
}
const result = `計算完了! 合計値:${sum}`;
console.log(result);
runOnJS(setResult)(result);
})();
};
return (
<View style={styles.container}>
<Text style={styles.title}>カスタムワークレットランタイム</Text>
<Text style={styles.description}>
特定用途のワークロード用に分離されたJavaScriptランタイムを作成します。
{'\n\n'}
これにより、UIスレッドやJSスレッドをブロックすることなく負荷の高い計算を並行して実行できます。
</Text>
<Button title="カスタムランタイムで実行" onPress={handlePress} />
{result && <Text style={styles.result}>{result}</Text>}
</View>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
padding: 20,
justifyContent: 'center',
},
title: {
fontSize: 24,
fontWeight: 'bold',
marginBottom: 12,
},
description: {
fontSize: 14,
color: '#666',
marginBottom: 20,
lineHeight: 20,
},
result: {
marginTop: 20,
fontSize: 16,
color: '#007AFF',
fontWeight: '500',
},
});
スレッドの切り替えの例
import React, { useState } from 'react';
import { Button, StyleSheet, View, Text, ScrollView } from 'react-native';
import { runOnUI, runOnJS } from '@amazon-devices/react-native-worklets';
/**
* スレッドの切り替えの例
* JavaScriptスレッドとUIスレッドを切り替えるデモを示します。
*/
export default function WorkletThreadSwitchExample() {
const [log, setLog] = useState<string[]>([]);
const addLog = (message: string) => {
setLog(prev => [...prev, message]);
};
const handlePress = () => {
setLog([]);
// JSスレッドで開始します。
addLog('1. JSスレッドで開始');
// UIスレッドに切り替えます。
runOnUI(() => {
'worklet';
console.log('2. UIスレッドで実行中');
runOnJS(addLog)('2. UIスレッドで実行中');
// UIスレッドで何らかの処理を行います。
const sum = Array.from({ length: 100 }, (_, i) => i).reduce((a, b) => a + b, 0);
console.log('3. UIスレッドで計算された合計値:', sum);
runOnJS(addLog)(`3. 計算された合計値:${sum}`);
// JSスレッドにコールバックします。
runOnJS(addLog)('4. JSスレッドに戻る');
})();
};
return (
<View style={styles.container}>
<Text style={styles.title}>スレッドの切り替え</Text>
<Text style={styles.description}>
runOnUIとrunOnJSを使用してJavaScriptスレッドとUIスレッドを切り替えるデモを行います。
</Text>
<Button title="スレッドを切り替え" onPress={handlePress} />
{log.length > 0 && (
<ScrollView style={styles.logContainer}>
{log.map((entry, index) => (
<Text key={index} style={styles.logEntry}>{entry}</Text>
))}
</ScrollView>
)}
</View>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
padding: 20,
},
title: {
fontSize: 24,
fontWeight: 'bold',
marginBottom: 12,
},
description: {
fontSize: 14,
color: '#666',
marginBottom: 20,
lineHeight: 20,
},
logContainer: {
marginTop: 20,
maxHeight: 300,
padding: 12,
backgroundColor: '#f5f5f5',
borderRadius: 8,
},
logEntry: {
fontSize: 14,
color: '#333',
marginVertical: 4,
},
});
API
Vegaのワークレットライブラリは、マルチスレッド処理、メモリ管理、ユーティリティ関数を含む包括的なAPIを提供します。
スレッド
| メソッド | 説明 |
|---|---|
createWorkletRuntime |
ワークレットを別のスレッドで実行するための新しいJSランタイムを作成します。 |
runOnUI |
ワークレット化された関数をUIスレッドで非同期的に実行します(非推奨)。 |
runOnUIAsync |
ワークレット化された関数をUIスレッドで非同期的に実行し、Promiseを返します。 |
runOnUISync |
ワークレット化された関数をUIスレッドで同期的に実行し、結果を返します。 |
runOnJS |
ワークレット化されていない関数をJSスレッドで非同期的に実行します(非推奨)。 |
runOnRuntime |
ワークレット化された関数をカスタムワークレットランタイムで実行します(非推奨)。 |
scheduleOnRN |
ワークレットをReact Native(JS)スレッドで実行するようにスケジュールします。 |
scheduleOnUI |
ワークレットをUIスレッドで実行するようにスケジュールします。 |
callMicrotasks |
現在のランタイムで保留中のすべてのマイクロタスクを処理します。 |
executeOnUIRuntimeSync |
コードをUIランタイムで同期的に実行します(非推奨)。 |
メモリ
| メソッド | 説明 |
|---|---|
createSerializable |
異なるJavaScriptランタイム間で受け渡すことができる、シリアル化可能なオブジェクトを作成します。 |
createSynchronizable |
指定された初期値を保持する新しいSynchronizableを作成します。 |
isSerializableRef |
値がシリアル化可能な参照かどうかをチェックします。 |
isSynchronizable |
値がSynchronizableかどうかをアサートします。 |
Synchronizable |
Serializableは共有メモリの一種で、異なるJavaScriptランタイム間でシリアル化および逆シリアル化できる不変の値を保持します。 |
makeShareable |
値をスレッド間で共有できるようにします(非推奨)。 |
makeShareableCloneRecursive |
値のクローンを再帰的に作成し、値を共有できるようにします(非推奨)。 |
makeShareableCloneOnUIRecursive |
値のクローンを再帰的に作成し、値をUIスレッドで共有できるようにします(非推奨)。 |
ユーティリティ
| メソッド | 説明 |
|---|---|
getRuntimeKind |
現在実行中のランタイムの種類を返します(1=JS、2=UI、3=ワーカー)。 |
isWorkletFunction |
関数がワークレットかどうかをチェックします。 |
Vegaでの例外
Vegaのワークレットライブラリには、APIサポートに関していくつかの例外があります。このセクションでは、これらの例外について説明します。
- 機能フラグは、Vegaでは現在サポートされていません。
- バンドルモードは、Vegaでは現在サポートされていません。
サポートされているバージョン
| NPMパッケージのバージョン | Vega SDKバージョン | Vega OSバージョン | React Nativeバージョン |
|---|---|---|---|
| ~1.0.0 | 0.24 | OS 1.2(2101020054720) |
0.83 |
クレジット
このプロジェクトは、Shopify、Expo.io(英語のみ)、Software Mansion(英語のみ)の協力により構築され、維持されています。
Last updated: 2026年7月13日

