Installation
Your first React Native WebGPU App
React Native WebGPU brings the WebGPU API to iOS, Android, macOS, and visionOS using Dawn.
Install the package
npm i react-native-webgpuRequirements
| Package | Version | Required |
|---|---|---|
react-native | >= 0.81.0 | Yes |
react-native-worklets | >= 0.7.2 | Optional - off-js-thread rendering |
Please note that this module does not work on the legacy architecture.
Setup
Once installed, the global navigator.gpu API is available - the same entry point as in Chrome or Safari:
const = await ..();
const = await !.();Rendering happens inside a Canvas view. The typical loop is:
- Get a WebGPU context from the canvas ref
- Configure the context with your device
- Encode render (or compute) passes
device.queue.submit(...)context.present()- required on React Native (Frame presentations)
Start with the Canvas view once installation is done.
Troubleshooting
Android emulators
On Android emulators, WebGPU may fall back to a software adapter. Rendering is slow and some features (especially native textures) may be unavailable. Use warnIfNotHardwareAccelerated to log a warning during development. Prefer physical devices for camera, video, and performance testing.
iOS Simulator - Metal API Validation
When running on the iOS Simulator, disable Metal API Validation in Xcode or you may hit false-positive errors and crashes that do not occur on device.
Steps: Product → Scheme → Edit Scheme → Run → Diagnostics → uncheck Metal API Validation.
Metal API Validation is a debug mode that checks every Metal call against the API specification. The simulator's Metal stack is not identical to real hardware, and validation can flag legitimate Dawn/WebGPU usage as invalid. Disabling it for local development is standard practice; keep validation enabled when debugging raw Metal code on device if needed.
Learn more in Apple's documentation on validating Metal API usage.
Next steps
- Expo - scaffold with the
with-webgputemplate - Canvas - your rendering surface
- Native APIs - the React Native specific differences
- Learn WebGPU - learn the low-level API