# wcandillon/react-native-webgpu architecture

> Architecture diagram of the GitHub repository wcandillon/react-native-webgpu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wcandillon/react-native-webgpu
- Repository: https://github.com/wcandillon/react-native-webgpu

## Overview

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: [`packages/webgpu/cpp/rnwgpu/api/GPU.h`](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/rnwgpu/api/GPU.h) (WebGPU API), [`externals/dawn`](https://github.com/wcandillon/react-native-webgpu/tree/main/externals/dawn) (Dawn), [`apps/example/src/Route.ts`](https://github.com/wcandillon/react-native-webgpu/blob/main/apps/example/src/Route.ts) (Routes), [`packages/webgpu/cpp/jsi/JSIConverter.h`](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/jsi/JSIConverter.h) (JSI core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_lib_js["Library JS API"]
  node_node_canvas["Canvas<br/>JS component<br/>[Canvas.tsx]"]
  node_node_offscreen["Offscreen<br/>JS helpers<br/>[Offscreen.ts]"]
  node_node_native_module["Native module<br/>JSI bridge"]
  node_node_view_component["View native<br/>platform component"]
  node_node_polyfill_module["Polyfill GPU<br/>runtime polyfill"]
  node_node_entry["Entry points<br/>package entry<br/>[index.tsx]"]
end

subgraph group_group_lib_native["Native Runtime"]
  node_node_jsi["JSI core<br/>runtime bridge<br/>[JSIConverter.h]"]
  node_node_async["Async runtime<br/>task dispatch<br/>[AsyncRunner.h]"]
  node_node_manager["RN manager<br/>native coordinator"]
  node_node_api_gpu["WebGPU API<br/>spec objects<br/>[GPU.h]"]
  node_node_api_canvas["Canvas context<br/>surface binding"]
  node_node_api_descriptors["Descriptors<br/>schema layer"]
  node_node_android["Android views<br/>native platform<br/>[WebGPUView.java]"]
  node_node_apple["Apple views<br/>native platform<br/>[WebGPUView.mm]"]
end

subgraph group_group_example["Example App"]
  node_node_example_app["Example app<br/>showcase app<br/>[App.tsx]"]
  node_node_route["Routes<br/>navigation<br/>[Route.ts]"]
  node_node_home["Home<br/>landing screen<br/>[Home.tsx]"]
  node_node_demos["Demos<br/>GPU showcases<br/>[HelloTriangle.tsx]"]
  node_node_threejs["Three.js<br/>integration stack<br/>[index.tsx]"]
  node_node_assets["Assets<br/>loading helpers<br/>[useAssets.ts]"]
end

subgraph group_group_backend["Backend"]
  node_node_dawn[("Dawn<br/>GPU backend")]
end

subgraph group_group_tooling["Tooling"]
  node_node_codegen["Codegen<br/>build generation<br/>[codegen.ts]"]
  node_node_build["Build scripts<br/>native packaging<br/>[dawn.ts]"]
  node_node_tests["Tests<br/>validation<br/>[GPU.spec.ts]"]
end

node_node_entry -->|"exports"| node_node_canvas
node_node_entry -->|"exports"| node_node_native_module
node_node_entry -->|"exports"| node_node_polyfill_module
node_node_canvas -->|"renders via"| node_node_view_component
node_node_polyfill_module -->|"registers"| node_node_jsi
node_node_native_module -->|"initializes"| node_node_manager
node_node_view_component -->|"android path"| node_node_android
node_node_view_component -->|"apple path"| node_node_apple
node_node_manager -->|"bridges"| node_node_jsi
node_node_jsi -->|"dispatches"| node_node_async
node_node_jsi -->|"wraps"| node_node_api_gpu
node_node_async -->|"coordinates"| node_node_api_gpu
node_node_api_gpu -->|"uses"| node_node_api_descriptors
node_node_api_canvas -->|"presents to"| node_node_dawn
node_node_api_gpu -->|"executes on"| node_node_dawn
node_node_android -->|"native backend"| node_node_dawn
node_node_apple -->|"native backend"| node_node_dawn
node_node_example_app -->|"navigates"| node_node_route
node_node_route -->|"starts at"| node_node_home
node_node_route -->|"opens"| node_node_demos
node_node_route -->|"opens"| node_node_threejs
node_node_demos -->|"uses"| node_node_canvas
node_node_threejs -->|"uses"| node_node_canvas
node_node_threejs -->|"loads"| node_node_assets
node_node_demos -->|"loads"| node_node_assets
node_node_codegen -->|"generates"| node_node_api_descriptors
node_node_build -->|"packages"| node_node_dawn
node_node_tests -->|"verifies"| node_node_api_gpu
node_node_tests -->|"verifies"| node_node_demos

click node_node_canvas "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/Canvas.tsx"
click node_node_offscreen "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/Offscreen.ts"
click node_node_native_module "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/NativeWebGPUModule.ts"
click node_node_view_component "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/WebGPUViewNativeComponent.ts"
click node_node_polyfill_module "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/WebPolyfillGPUModule.ts"
click node_node_entry "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/index.tsx"
click node_node_jsi "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/jsi/JSIConverter.h"
click node_node_async "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/rnwgpu/async/AsyncRunner.h"
click node_node_manager "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/rnwgpu/RNWebGPUManager.cpp"
click node_node_api_gpu "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/rnwgpu/api/GPU.h"
click node_node_api_canvas "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/rnwgpu/api/GPUCanvasContext.cpp"
click node_node_api_descriptors "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/rnwgpu/api/descriptors/GPURenderPipelineDescriptor.h"
click node_node_android "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/android/src/main/java/com/webgpu/WebGPUView.java"
click node_node_apple "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/apple/WebGPUView.mm"
click node_node_dawn "https://github.com/wcandillon/react-native-webgpu/tree/main/externals/dawn"
click node_node_example_app "https://github.com/wcandillon/react-native-webgpu/blob/main/apps/example/src/App.tsx"
click node_node_route "https://github.com/wcandillon/react-native-webgpu/blob/main/apps/example/src/Route.ts"
click node_node_home "https://github.com/wcandillon/react-native-webgpu/blob/main/apps/example/src/Home.tsx"
click node_node_demos "https://github.com/wcandillon/react-native-webgpu/blob/main/apps/example/src/Triangle/HelloTriangle.tsx"
click node_node_threejs "https://github.com/wcandillon/react-native-webgpu/blob/main/apps/example/src/ThreeJS/index.tsx"
click node_node_assets "https://github.com/wcandillon/react-native-webgpu/blob/main/apps/example/src/components/useAssets.ts"
click node_node_codegen "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/scripts/codegen/codegen.ts"
click node_node_build "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/scripts/build/dawn.ts"
click node_node_tests "https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/__tests__/GPU.spec.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_canvas,node_node_offscreen,node_node_native_module,node_node_view_component,node_node_polyfill_module,node_node_entry toneBlue
class node_node_jsi,node_node_async,node_node_manager,node_node_api_gpu,node_node_api_canvas,node_node_api_descriptors,node_node_android,node_node_apple toneAmber
class node_node_example_app,node_node_route,node_node_home,node_node_demos,node_node_threejs,node_node_assets toneMint
class node_node_dawn toneRose
class node_node_codegen,node_node_build,node_node_tests toneIndigo
```

## Components

### Library JS API

Public React Native WebGPU entrypoints and platform-facing JS glue.

- [Canvas](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/Canvas.tsx): JS component · Cross-platform canvas surface used by React Native screens. · `packages/webgpu/src/Canvas.tsx`
- [Offscreen](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/Offscreen.ts): JS helpers · Offscreen and worker-oriented WebGPU helpers. · `packages/webgpu/src/Offscreen.ts`
- [Native module](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/NativeWebGPUModule.ts): JSI bridge · Registers WebGPU globals and exposes native capability access. · `packages/webgpu/src/NativeWebGPUModule.ts`
- [View native](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/WebGPUViewNativeComponent.ts): platform component · JS-facing native view bindings for canvas presentation. · `packages/webgpu/src/WebGPUViewNativeComponent.ts`
- [Polyfill GPU](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/WebPolyfillGPUModule.ts): runtime polyfill · Browser-style GPU module registration and shims. · `packages/webgpu/src/WebPolyfillGPUModule.ts`
- [Entry points](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/index.tsx): package entry · 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](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/jsi/JSIConverter.h): runtime bridge · Object identity, runtime-aware caching, and JS-native conversion helpers. · `packages/webgpu/cpp/jsi/JSIConverter.h`
- [Async runtime](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/rnwgpu/async/AsyncRunner.h): task dispatch · Promise handling, microtasks, lifecycle monitoring, and thread dispatch. · `packages/webgpu/cpp/rnwgpu/async/AsyncRunner.h`
- [RN manager](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/rnwgpu/RNWebGPUManager.cpp): native coordinator · Top-level React Native WebGPU manager and surface registry. · `packages/webgpu/cpp/rnwgpu/RNWebGPUManager.cpp`
- [WebGPU API](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/rnwgpu/api/GPU.h): spec objects · Spec-matching WebGPU object model: GPU, device, queue, buffers, textures, passes, pipelines. · `packages/webgpu/cpp/rnwgpu/api/GPU.h`
- [Canvas context](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/rnwgpu/api/GPUCanvasContext.cpp): surface binding · Canvas configuration and present path for swapchain-backed rendering. · `packages/webgpu/cpp/rnwgpu/api/GPUCanvasContext.cpp`
- [Descriptors](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/cpp/rnwgpu/api/descriptors/GPURenderPipelineDescriptor.h): schema layer · Large descriptor and enum hierarchy translated from the WebGPU spec. · `packages/webgpu/cpp/rnwgpu/api/descriptors/GPURenderPipelineDescriptor.h`
- [Android views](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/android/src/main/java/com/webgpu/WebGPUView.java): native platform · Android module and surface implementations for WebGPU presentation. · `packages/webgpu/android/src/main/java/com/webgpu/WebGPUView.java`
- [Apple views](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/apple/WebGPUView.mm): native platform · 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](https://github.com/wcandillon/react-native-webgpu/blob/main/apps/example/src/App.tsx): showcase app · Cross-platform routed demo app that exercises the library. · `apps/example/src/App.tsx`
- [Routes](https://github.com/wcandillon/react-native-webgpu/blob/main/apps/example/src/Route.ts): navigation · Gallery-style routing between demo screens. · `apps/example/src/Route.ts`
- [Home](https://github.com/wcandillon/react-native-webgpu/blob/main/apps/example/src/Home.tsx): landing screen · Entry screen for the demo gallery. · `apps/example/src/Home.tsx`
- [Demos](https://github.com/wcandillon/react-native-webgpu/blob/main/apps/example/src/Triangle/HelloTriangle.tsx): GPU showcases · Representative demo screens for triangles, cubes, compute, textures, queries, diagnostics, and more. · `apps/example/src/Triangle/HelloTriangle.tsx`
- [Three.js](https://github.com/wcandillon/react-native-webgpu/blob/main/apps/example/src/ThreeJS/index.tsx): integration stack · Higher-level 3D framework integration with custom renderer, assets, and controls. · `apps/example/src/ThreeJS/index.tsx`
- [Assets](https://github.com/wcandillon/react-native-webgpu/blob/main/apps/example/src/components/useAssets.ts): loading helpers · 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](https://github.com/wcandillon/react-native-webgpu/tree/main/externals/dawn): GPU backend · Vendored native WebGPU implementation used as the execution backend. · `externals/dawn`

### Tooling

Build, codegen, and validation pipeline.

- [Codegen](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/scripts/codegen/codegen.ts): build generation · Descriptor and hybrid object code generation for the native API layer. · `packages/webgpu/scripts/codegen/codegen.ts`
- [Build scripts](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/scripts/build/dawn.ts): native packaging · Dawn configuration, artifact copying, and install pipeline. · `packages/webgpu/scripts/build/dawn.ts`
- [Tests](https://github.com/wcandillon/react-native-webgpu/blob/main/packages/webgpu/src/__tests__/GPU.spec.ts): validation · API and demo coverage validating both the WebGPU implementation and rendering runtime. · `packages/webgpu/src/__tests__/GPU.spec.ts`

## Connections

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