React Native WebGPU

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-webgpu

Requirements

Minimum version
React Native0.81.0, with the New Architecture
iOS15.1
tvOS15.1
macOS14.0
AndroidAPI 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:

  1. Get a WebGPU context from the canvas ref
  2. Configure the context with your device
  3. Encode render (or compute) passes
  4. device.queue.submit(...)
  5. 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:

  1. Use React Native 0.87 or newer. Earlier releases have no SwiftPM autolinking, so keep CocoaPods there.
  2. From your app's ios directory, run npx react-native spm add --deintegrate once. It removes CocoaPods from the project and adds the Swift packages to the .xcodeproj. Then build the project (not a workspace) as usual.
  3. Do not run pod install in 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:

app.json
{
  "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