How wcandillon/react-native-webgpu works
1. Repository shape
- This is a monorepo with two main products: packages/webgpu, the reusable React Native WebGPU library, and apps/example, a cross-platform showcase app that exercises the API and serves as the integration test bed.
- The repo also vendors externals/dawn, the native WebGPU implementation the library is built on.
2. Top-level architecture boundary
- The library is designed as a React Native WebGPU runtime for the new architecture only; the README explicitly says it requires React Native 0.81+ and does not support the legacy bridge.
- The public API is intended to match browser WebGPU closely, so the app-side code can look like Web code with navigator.gpu, Canvas, GPUDevice, GPUCanvasContext, and present().
3. JavaScript/TypeScript API layer
- packages/webgpu/src is the JS entry surface. It exports the cross-platform canvas component, hooks, polyfills, type definitions, and platform entry points (main/index.tsx, main/index.web.tsx).
- Canvas.tsx, Offscreen.ts, NativeWebGPUModule.ts, and WebGPUViewNativeComponent* are the main JS-facing integration points for rendering and native capability access.
4. Native module and view layer
- Native rendering is anchored around a canvas view component plus a module that registers WebGPU globals and objects into the React Native runtime.
- On Android, the package includes Java view/module classes under packages/webgpu/android/src/main/java/com/webgpu; on Apple platforms, the equivalent lives in packages/webgpu/apple/*.mm and related headers.
- The important runtime boundary is: JS creates/configures WebGPU objects, while native code owns the actual surface, platform windowing, and GPU-backed presentation.
5. C++ core abstraction layer
- The bulk of the WebGPU object model is implemented in C++ under packages/webgpu/cpp/rnwgpu/api.
- These classes mirror the WebGPU spec: GPU, GPUAdapter, GPUDevice, GPUQueue, buffers, textures, pipelines, passes, query sets, samplers, errors, and the large descriptor hierarchy.
- This C++ layer is the spec-to-native translation layer that sits between JS/JSI and Dawn.
6. JSI and async execution
- packages/webgpu/cpp/jsi and packages/webgpu/cpp/rnwgpu/async handle object identity, runtime-aware caching, promises, lifecycle monitoring, and task dispatch across React Native threads.
- This matters architecturally because many WebGPU operations are asynchronous and many objects are passed between JS and worklets; the repo explicitly supports Reanimated/worklet serialization.
7. Dawn backend and build pipeline
- Dawn is the underlying GPU backend, pulled in as a submodule and built or downloaded through scripts in packages/webgpu/scripts/build and packages/webgpu/scripts/install-dawn.ts.
- The build tooling copies platform artifacts, configures Dawn, and packages binaries for Android, Apple, and the JS package.
- In other words, the repo is not implementing a GPU backend itself; it is a React Native binding layer on top of Dawn.
8. Platform-specific UI integration
- Android has multiple surface implementations (WebGPUSurfaceView, WebGPUTextureView, WebGPUAHBView, etc.), suggesting support for different presentation paths and hardware buffer integration.
- Apple has a Metal-based view stack (MetalView, WebGPUView, WebGPUModule, ApplePlatformContext) and also ships prebuilt support for macOS and visionOS.
- The platform views are where WebGPU canvas presentation is connected to native UI surfaces.
9. Example app as architecture showcase
- apps/example is a multi-screen React Native app organized by feature area: triangles, cubes, compute, textures, shadows, storage buffers, occlusion queries, diagnostics, TensorFlow, Three.js, Reanimated, and more.
- src/Route.ts and src/Home.tsx indicate a routed gallery of demos rather than a single app flow.
- Each demo folder encapsulates one GPU capability and usually includes its own shaders, supporting utilities, and entry component.
10. Three.js / React Three Fiber integration path
- The apps/example/src/ThreeJS subtree is a separate integration stack for higher-level 3D frameworks, with custom renderer setup, asset management, Orbit controls, and scene components.
- The README notes a Metro resolution tweak for Three.js and a package patch for @react-three/fiber, which shows this repo supports those ecosystems but needs module-resolution alignment to the WebGPU build.
11. Assets, loaders, and polyfills
- The example app includes an asset pipeline for models, HDRs, textures, and cubemaps, plus a resolveAssetSourcePolyfill.js and useAssets helper.
- The README’s createImageBitmap guidance reflects an important architectural boundary: browser-style texture loading is emulated so GPU textures can be created from React Native asset URIs and fetched blobs.
12. Validation and capability coverage
- The packages/webgpu/src/__tests__ suite covers low-level API behavior (Buffer, Device, Texture, ErrorScope, ExternalTexture, shaders, constants) and higher-level demo behavior.
- This tells you the library is validated both as a WebGPU API implementation and as a rendering runtime, not just as a UI component wrapper.
13. Tooling and CI
- The repo uses Yarn 3, Turborepo, GitHub Actions, ESLint/Jest, and cpplint.
- CI is split between general checks and C++ linting, which reflects the mixed JavaScript/C++/native nature of the codebase.
14. Main data flow to diagram
- A React Native screen obtains a Canvas ref, requests a GPU adapter/device, configures a canvas context, records commands, submits them to the queue, and then calls context.present().
- The call chain crosses from JS into JSI/C++ object wrappers, then into Dawn/native platform code, and finally into a platform surface on Android or Apple devices.
Main entry points: GPU.h WebGPU API · dawn Dawn · Route.ts Routes · JSIConverter.h JSI core
Components 24
Library JS API
Public React Native WebGPU entrypoints and platform-facing JS glue.
- Canvas · Cross-platform canvas surface used by React Native screens.
packages/webgpu/src/Canvas.tsx - Offscreen · Offscreen and worker-oriented WebGPU helpers.
packages/webgpu/src/Offscreen.ts - Native module · Registers WebGPU globals and exposes native capability access.
packages/webgpu/src/NativeWebGPUModule.ts - View native · JS-facing native view bindings for canvas presentation.
packages/webgpu/src/WebGPUViewNativeComponent.ts - Polyfill GPU · Browser-style GPU module registration and shims.
packages/webgpu/src/WebPolyfillGPUModule.ts - Entry points · Main package exports for native and web targets.
packages/webgpu/src/index.tsx
Native Runtime
JSI, async dispatch, and platform-specific native integration.
- JSI core · Object identity, runtime-aware caching, and JS-native conversion helpers.
packages/webgpu/cpp/jsi/JSIConverter.h - Async runtime · Promise handling, microtasks, lifecycle monitoring, and thread dispatch.
packages/webgpu/cpp/rnwgpu/async/AsyncRunner.h - RN manager · Top-level React Native WebGPU manager and surface registry.
packages/webgpu/cpp/rnwgpu/RNWebGPUManager.cpp - WebGPU API · Spec-matching WebGPU object model: GPU, device, queue, buffers, textures, passes, pipelines.
packages/webgpu/cpp/rnwgpu/api/GPU.h - Canvas context · Canvas configuration and present path for swapchain-backed rendering.
packages/webgpu/cpp/rnwgpu/api/GPUCanvasContext.cpp - Descriptors · Large descriptor and enum hierarchy translated from the WebGPU spec.
packages/webgpu/cpp/rnwgpu/api/descriptors/GPURenderPipelineDescriptor.h - Android views · Android module and surface implementations for WebGPU presentation.
packages/webgpu/android/src/main/java/com/webgpu/WebGPUView.java - Apple views · Metal-backed view and module stack for Apple platforms.
packages/webgpu/apple/WebGPUView.mm
Example App
Cross-platform showcase app and integration test bed.
- Example app · Cross-platform routed demo app that exercises the library.
apps/example/src/App.tsx - Routes · Gallery-style routing between demo screens.
apps/example/src/Route.ts - Home · Entry screen for the demo gallery.
apps/example/src/Home.tsx - Demos · Representative demo screens for triangles, cubes, compute, textures, queries, diagnostics, and more.
apps/example/src/Triangle/HelloTriangle.tsx - Three.js · Higher-level 3D framework integration with custom renderer, assets, and controls.
apps/example/src/ThreeJS/index.tsx - Assets · Asset resolution, bitmap polyfill, and texture/model loading helpers.
apps/example/src/components/useAssets.ts
Backend
Vendored Dawn GPU implementation used by the binding layer.
- Dawn · Vendored native WebGPU implementation used as the execution backend.
externals/dawn
Tooling
Build, codegen, and validation pipeline.
- Codegen · Descriptor and hybrid object code generation for the native API layer.
packages/webgpu/scripts/codegen/codegen.ts - Build scripts · Dawn configuration, artifact copying, and install pipeline.
packages/webgpu/scripts/build/dawn.ts - Tests · API and demo coverage validating both the WebGPU implementation and rendering runtime.
packages/webgpu/src/__tests__/GPU.spec.ts
Connections 29
- Entry points → Canvas: exports · Package entry surface exposes the canvas component.
- Entry points → Native module: exports · Package entry surface exposes the native WebGPU runtime module.
- Entry points → Polyfill GPU: exports · Package entry surface wires browser-style GPU polyfills.
- Canvas → View native: renders via · Canvas mounts into the platform view binding.
- Polyfill GPU → JSI core: registers · Polyfill hooks register GPU globals through JSI.
- Native module → RN manager: initializes · Native module delegates runtime setup to the RN manager.
- View native → Android views: android path · Android uses native surface and module implementations.
- View native → Apple views: apple path · Apple uses Metal-backed view and module implementations.
- RN manager → JSI core: bridges · Manager participates in JS-to-native object exposure and identity.
- JSI core → Async runtime: dispatches · JSI layer hands async work to the task and microtask runtime.
- JSI core → WebGPU API: wraps · JSI conversion wraps the WebGPU object model.
- Async runtime → WebGPU API: coordinates · Async execution supports promise-returning WebGPU operations.
- WebGPU API → Descriptors: uses · Core WebGPU objects consume descriptor and enum definitions.
- Canvas context → Dawn: presents to · Canvas context ultimately presents GPU output through Dawn-backed surfaces.
- WebGPU API → Dawn: executes on · Spec objects translate into Dawn calls and resources.
- Android views → Dawn: native backend · Android platform code binds surfaces to the shared GPU backend.
- Apple views → Dawn: native backend · Apple platform code binds Metal presentation to the shared GPU backend.
- Example app → Routes: navigates · The example app routes between demo screens.
- Routes → Home: starts at · Routing begins from the home gallery screen.
- Routes → Demos: opens · Routes connect to the demo screens and capability showcases.
- Routes → Three.js: opens · Routes also reach the Three.js integration stack.
- Demos → Canvas: uses · Demo screens acquire a canvas and drive WebGPU rendering.
- Three.js → Canvas: uses · Three.js integration renders through the shared canvas path.
- Three.js → Assets: loads · 3D integration relies on model, texture, and HDR asset helpers.
- Demos → Assets: loads · Demo screens use asset helpers for textures and media.
- Codegen → Descriptors: generates · Code generation produces much of the descriptor layer.
- Build scripts → Dawn: packages · Build scripts configure and package Dawn artifacts.
- Tests → WebGPU API: verifies · Tests cover core API behavior and spec compliance.
- Tests → Demos: verifies · Tests also cover representative demo behavior.