Skip to content

chore(🐙): minor doc update #450

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wcandillon merged 1 commit into from
Aug 21, 2026
Merged

chore(🐙): minor doc update #450

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 6 additions & 8 deletions apps/docs/content/api/install-webgpu.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ runOnRuntime(runtime, gpuWork)(device);

### navigator.gpu on a worklet runtime

After `installWebGPU()`, a worklet can request its own adapter and device instead of receiving them from the main thread. The returned promises settle on the calling runtime.
After `installWebGPU()`, read `navigator` through `globalThis.navigator` inside a worklet. The Worklets babel plugin does not currently treat a bare `navigator` as a known global, so without the prefix it captures the main runtime's `navigator` object by closure instead of reading the one installed on the worklet runtime. This is fixed upstream ([software-mansion/react-native-reanimated#10364](https://github.com/software-mansion/react-native-reanimated/pull/10364)); once you are on a version of `react-native-worklets` that includes it, a bare `navigator` works and the prefix is no longer needed.

```tsx twoslash
import { installWebGPU } from "react-native-webgpu";
Expand All @@ -85,17 +85,15 @@ import { runOnUI } from "react-native-worklets";
runOnUI(() => {
"worklet";
installWebGPU();
const format = globalThis.navigator.gpu.getPreferredCanvasFormat();
globalThis.navigator.gpu.requestAdapter().then((adapter) => {
// …
});
})();
```

## Known limitations
If you create a device on the worklet runtime, beware that spontaneous device events are only delivered for devices created on the main JS runtime:
- `device.lost` read on a worklet runtime returns a promise that never settles, unless the device is already lost at that point, in which case it resolves normally.
- `uncapturederror` listeners registered on a device created on a worklet runtime never fire.

* `globalThis.navigator` instead of `navigator`: inside a worklet, read `navigator` through `globalThis.navigator`. The Worklets babel plugin does not currently treat a bare `navigator` as a known global, so without the prefix it captures the main runtime's `navigator` object by closure instead of reading the one installed on the worklet runtime. This is fixed upstream ([software-mansion/react-native-reanimated#10364](https://github.com/software-mansion/react-native-reanimated/pull/10364)); once you are on a version of `react-native-worklets` that includes it, a bare `navigator` works and the prefix is no longer needed.
* `device.lost` and `uncapturederror` are main-thread only: spontaneous device events are only delivered for devices created on the main JS runtime:
- `device.lost` read on a worklet runtime returns a promise that never settles, unless the device is already lost at that point, in which case it resolves normally.
- `uncapturederror` listeners registered on a device created on a worklet runtime never fire.

If you need to observe device loss or uncaptured errors, create the device on the main JS thread, attach the handlers there, and pass the device into the worklet.
If you need to observe device loss or uncaptured errors, create the device on the main JS thread, attach the handlers there, and pass the device into the worklet.
Loading