Installation
Install the package and check the requirements.
React Native WebGPU brings the WebGPU API to iOS, tvOS, Android, and macOS using Dawn. visionOS is not supported at the moment: the Dawn binaries do not ship a visionOS slice.
Install the package
npm i react-native-webgpuRequirements
| Minimum version | |
|---|---|
| React Native | 0.81.0, with the New Architecture |
| iOS | 15.1 |
| tvOS | 15.1 |
| macOS | 14.0 |
| Android | API level 26 (minSdkVersion = 26) |
| Worklets (optional) | react-native-worklets@>=0.7.2, for off-js-thread rendering |
An Android app with a lower minSdkVersion fails to build; on Expo, the config plugin raises it for you.
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.
Testing with Jest
react-native-webgpu wraps a native module, which isn't available under Jest. Add its mock to setupFilesAfterEnv in your jest.config.js:
// jest.config.js
module.exports = {
// Other values
setupFilesAfterEnv: [
"react-native-webgpu/jestSetup.js",
],
};This replaces the package with a JS-only stand-in: <Canvas> renders as a plain View so screens built around it can still be rendered in tests, while APIs that need a GPU (useDevice, a real canvas context, and so on) throw a clear error if a test actually exercises them.
Optional: Swift Package Manager on iOS
By default, react-native-webgpu links on iOS/macOS through CocoaPods autolinking, with no extra setup. The long-term plan is to move the Apple platforms to Swift Package Manager. It is available today as an alternative: the package also ships a Package.swift for React Native's SwiftPM autolinking, which needs no CocoaPods at all:
- Use React Native 0.87 or newer. Earlier releases have no SwiftPM autolinking, so keep CocoaPods there.
- From your app's
iosdirectory, runnpx react-native spm add --deintegrateonce. It removes CocoaPods from the project and adds the Swift packages to the.xcodeproj. Then build the project (not a workspace) as usual. - Do not run
pod installin that app: it would re-integrate CocoaPods and break the Swift packages.
Dawn comes as a prebuilt binary that Xcode downloads the first time it resolves packages.
With React Native Skia v3 installed alongside, package resolution checks that both packages link the same Dawn release, and fails if they are not at compatible versions. After changing either version, reset the package caches in Xcode (File > Packages > Reset Package Caches) if the error persists.
Platform coverage
The Swift package targets iOS only: tvOS, macOS and Android still require the CocoaPods/Gradle autolinked path. See spm-example at the root of the React Native WebGPU repo for a working reference project, and its README for the gotchas (stale Package.resolved, the stub Podfile).
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.
Expo: add the config plugin that ships with react-native-webgpu to your app config: it disables the setting automatically on every prebuild:
{
"expo": {
"plugins": ["react-native-webgpu"]
}
}Bare React Native: Product → Scheme → Edit Scheme → Run → Diagnostics → uncheck Metal API Validation.
The simulator's Metal stack is not identical to real hardware, and validation can flag legitimate Dawn/WebGPU usage as invalid. The setting only affects debug runs from Xcode, not release builds.
Learn more in Apple's documentation on validating Metal API usage.
Android builds without network access
Gradle downloads the prebuilt Dawn from the GitHub releases of React Native Skia, which builds it, the first time it builds, only for the architectures being built, and caches it like any other Gradle dependency. To download it from a mirror or a local directory instead, set the reactNativeSkiaBinariesUrl Gradle property (or the REACT_NATIVE_SKIA_BINARIES_URL environment variable) to a URL or a file:/// directory that holds the release assets under binaries-<version>/.
Next steps
- Expo: scaffold the hosted WebGPU examples template
- Canvas: your rendering surface
- Platform Guide: the React Native specific differences
- Learn WebGPU: learn the low-level API